Micro Focus Enterprise Server for .NET 5.0

Welcome to Enterprise Server for .NET

  • 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
Related concepts
Introduction to Enterprise Server for .NET
System Architecture
Quick Start


Product Information

This Product Information covers information available at the time of writing. Up-to-date information is downloadable from the Micro Focus SupportLine Web site.


Supported Operating Systems and Third-party Software

Lists operating systems supported and tested with the 5.0 release of Micro Focus software products, and third-party software supported by major features within those Micro Focus products.
Attention: This provides a summary of operating systems and third-party software supported across the Micro Focus Visual COBOL / Enterprise Developer suite of products. Not all software and/or software versions listed here are supported by every product in the suite.
  • Windows Operating Systems
  • Linux/UNIX Operating Systems
  • IBM Mainframe Operating Systems
  • Integrated Development Environments (IDEs)
  • .NET Core
  • Java JDK
  • Java Application Servers
  • Relational Database Management Systems (RDBMSs)
  • Database Client Software
  • Middleware

Windows Operating Systems

Back to Top

All supported Windows operating system versions have been tested with the 5.0 release of each Micro Focus product. Each listed Windows operating system version and its subsequent updates are supported.

Operating System Base
Windows 7
Windows 8.1
Windows 10
Windows Server 2008 R2 SP1
Windows Server 2012 R2
Windows Server 2016
Windows Server 2019

Linux/UNIX Operating Systems

Back to Top

Micro Focus has tested the operating system base versions with the 5.0 release of each Micro Focus product. Each given operating system base release is supported along with any subsequent minor releases provided by the vendor.

Operating System Base | Processor
AIX 7.1.x (where x >=4)1 | IBM Power System2
AIX 7.2 1 | IBM Power System2
CentOS 7 1 | Intel x86-64
CentOS 8 | Intel x86-64
HP - UX 11.31 1 | Itanium
Oracle Linux - Red Hat Compatible Kernel 6 1 | Intel x86-64
Oracle Linux - Red Hat Compatible Kernel 7 1 | Intel x86-64
Oracle Linux - Red Hat Compatible Kernel 8 1 | Intel x86-64
Oracle Linux - Unbreakable Enterprise Kernel 6 1 | Intel x86-64
Oracle Linux - Unbreakable Enterprise Kernel 7 1 | Intel x86-64
Oracle Linux - Unbreakable Enterprise Kernel 8 1 | Intel x86-64
Red Hat Enterprise Linux 6 | Intel x86-64 1
Red Hat Enterprise Linux 6 | IBM Z System1
Red Hat Enterprise Linux 7 | IBM Power System 1,2
Red Hat Enterprise Linux 7 | Intel x86-64
Red Hat Enterprise Linux 7 | IBM Z System1
Oracle Solaris 11 1 | Intel x86-64
Oracle Solaris 11 1 | SPARC
SUSE Linux Enterprise Server 12 | IBM Power System 1
SUSE Linux Enterprise Server 15 | IBM Power System 1
SUSE Linux Enterprise Server 12 | Intel x64
SUSE Linux Enterprise Server 15 | Intel x64
SUSE Linux Enterprise Server 12 | IBM Z System 1
SUSE Linux Enterprise Server 15 | IBM Z System 1
1 Not supported by Eclipse. 2 64-bit-only environments

IBM Mainframe Operating Systems

Back to Top

Operating System
z/OS 2.3
z/OS 2.4

Integrated Development Environments (IDEs)

Back to Top

Microsoft Visual Studio 2017
Microsoft Visual Studio 2019
Eclipse v4.7
Eclipse v4.8
Microsoft VS Code v1.x

.NET Core

Back to Top

.NET Core 2.1
.NET Core 3.1

Java JDK

Back to Top

IBM JDK 1.7
IBM JDK 1.8
Oracle JDK 1.7 / 7
Oracle JDK 1.8 / 8
AdoptOpenJDK 8

Java Application Servers

Back to Top

Apache Tomcat 9.0
IBM WebSphere 8.5.5
IBM WebSphere 9.0
IBM WebSphere Liberty 19.0.0.01
JBoss EAP 7.1
Oracle WebLogic 12.2.1
1 Websphere Liberty is made available as a single stream continuous delivery software lifecycle. Micro Focus does not test all updates to Liberty but does periodically test the latest release of WebSphere Liberty against the latest available Micro Focus product release.

Micro Focus makes reasonable efforts to resolve product issues against supported releases of Liberty and in accordance with the Micro Focus product lifecycle policy. Micro Focus might require you to update to a newer release of Liberty to remedy a Support case.

Relational Database Management Systems (RDBMSs)

Back to Top

All RDBMS testing is done on both 32- and 64-bit platforms based on RDBMS client software availability.

Oracle 12.2, 12.2.0.1
Oracle 18c (12.2.0.2)
Microsoft SQL Server 2012
Microsoft SQL Server 2014
Microsoft SQL Server 2016
Microsoft SQL Server 2017
IBM DB2 LUW 10.5
IBM DB2 LUW 11.1
EDB PostgreSQL 10.x
GDG PostgreSQL 10.x
MySQL 5.7

Database Client Software

Back to Top

Client | Release | Micro Focus Component(s)
.NET Core database providers | Consult the RDBMS documentation specific to your installed RDBMS to determine which version(s) of .NET Core are compatible. | OpenESQL
ADO.NET | Consult the RDBMS documentation specific to your installed RDBMS to determine which version(s) of ADO.NET are compatible. | OpenESQL HCOSS
IBM Data Server Runtime Client, which includes Database Connectors, CLI, Database Connectors, and ADO.NET | Consult the IBM documentation specific to your installed RDBMS to determine which version(s) of IBM Data Server Runtime Client are compatible. | OpenESQL DB2 DB2 for HCO
IBM Data Server Client | Consult the IBM documentation specific to your installed RDBMS to determine which version(s) of IBM Data Server Client are compatible. | OpenESQL DB2 ECM
Oracle Client and Oracle Instant Client with Pro*COBOL | Consult the Oracle documentation specific to your installed RDBMS to determine which version(s) of Oracle Client or Oracle Instant Client are compatible. | OpenESQL COBSQL
IBM Informix ESQL/COBOL 1 | 7.3 or later |
Database Connectors Drivers | Consult the RDBMS documentation specific to your installed RDBMS to determine which version(s) of Database Connectors Drivers are compatible. | OpenESQL
Microsoft OLE DB Provider for DB2 | Consult the SQL Server documentation specific to your installed RDBMS to determine which version(s) of Database Connectors Drivers are compatible. | HCOSS
Microsoft OLE DB Provider for SQL Server | Consult the SQL Server documentation specific to your installed RDBMS to determine which version(s) of Database Connectors Drivers are compatible. | HCOSS
Database Connectors Drivers | ODBC 3.0-compliant drivers |
Sybase Open Client Embedded SQL/COBOL 1 | 11.1 or later |
1 Not tested.

Middleware

Back to Top

IBM WebSphere MQ 9.0
IBM TXSeries for Multiplatforms 1
Oracle Tuxedo and Tuxedo ART 2
1 See the IBM Web site for a list of supported versions.

2 See the Oracle Web site for a list of supported versions.


Updates and Product Support

When you have installed, you need to apply the latest updates if there are any. .

Before you can access the Software Licenses and Downloads page, you need to register (first-time users only) and log in with Product Support. To register:

  1. Click Register on the Software Licenses and Downloads page.
  2. Enter your details. You will need your product serial numbers, which you can find .

To log in:

  1. Enter your User Name and Password on the Software Licenses and Downloads page.

    We recommend you check Auto Login so you don't have to do this every time.

  2. Click Login.

The Software Licenses and Downloads page is now displayed, where you can find the latest update for your product and version number.

  1. Log into the Software Licenses and Downloads (SLD) site at https://sld.microfocus.com/mysoftware/download/downloadCenter .
  2. Select your account and click Entitlements.
  3. Search for the product by using any of the available search parameters.
  4. Click Show all entitlements.
  5. Click Get Software in the Action column for the product you want to download or update.

    In the File Type column, you see entries for "Software" for any GA products, and "Patch" for any patch updates.

  6. Click Download on the relevant row.

You will then be notified on a weekly basis, when you run this COBOL development system, if an update is available. The notification will include a link to the Product Support page from where you can access the update, as described above.

Product Support is a web-based support and information service from Micro Focus. It provides all the latest information and software updates for this COBOL development system:

  • Technical support information
  • Latest product information
  • Documentation updates
  • New and updated demonstrations and templates
  • Hints and tips
  • Lots more - try it and see!


Micro Focus End User License Agreement

  • MICRO FOCUS® ENTERPRISE DEVELOPER v5
  • MICRO FOCUS ENTERPRISE SERVER v5
  • MICRO FOCUS ENTERPRISE SERVER FOR .NET v5
  • MICRO FOCUS ENTERPRISE TEST SERVER v5
  • MICRO FOCUS ENTERPRISE TEST SERVER PREMIUM v5
  • VISUAL COBOL® v5
  • COBOL SERVER v5
  • DATABASE CONNECTORS v5

IMPORTANT: LICENSOR IS PROVIDING THIS LICENSED SOFTWARE TO LICENSEE (THE ORIGINAL PURCHASER EITHER AS AN INDIVIDUAL OR ON BEHALF OF ANOTHER LEGAL ENTITY AS ITS EMPLOYEE OR AUTHORIZED AGENT) FOR ITS USE SUBJECT TO LICENSEE’S AGREEMENT TO THE TERMS AND CONDITIONS SET FORTH BELOW. THESE TERMS AND CONDITIONS MAY BE DIFFERENT FROM THE END USER LICENSE AGREEMENT(S) THAT ACCOMPANIED EARLIER RELEASES OF THE LICENSED SOFTWARE. PLEASE READ THEM CAREFULLY TO ENSURE FULL UNDERSTANDING BEFORE PROCEEDING, AS THEY MAY CONTAIN ADDITIONAL RESTRICTIONS ON YOUR USE OF THE SOFTWARE. PLEASE DIRECT ANY QUESTIONS TO THE MICRO FOCUS LEGAL DEPARTMENT AT LEGALDEPT@MICROFOCUS.COM. IF YOU DO NOT AGREE TO THE TERMS AND CONDITIONS OF THIS LICENSE AGREEMENT, YOU WILL NOT BE AUTHORIZED TO USE THE LICENSED SOFTWARE. BY CLICKING THE ACCEPT BUTTON OR SIMILAR ACCEPTANCE MECHANISM DURING INSTALLATION, OR BY COPYING OR USING THE LICENSED SOFTWARE, LICENSEE ACKNOWLEDGES THAT IT HAS READ THIS LICENSE AGREEMENT, UNDERSTOOD IT, AND AGREED TO BE BOUND BY ITS TERMS AND CONDITIONS. THE LICENSED SOFTWARE IS LICENSED NOT SOLD.

For this End User License Agreement ("License Agreement") the following terms shall have the meanings given below:

"Documentation" means the Licensor user documentation that is included with the Licensed Software.

"Licensee" means the single legal entity or person that rightfully acquires the Licensed Software from Licensor or from a distributor or reseller of Licensor.

"License Options" means those license options set forth in Annex 1 to this License Agreement.

"Licensor" means the Micro Focus legal entity authorized to license the Licensed Software in the country in which Licensee acquires the Licensed Software.

"Licensed Software" means the object code version of the Licensor computer program(s) listed above, their Documentation, and other supplemental materials, as provided to Licensee by Licensor, including but not limited to any software security keys relating thereto. The Documentation may be delivered electronically and may only be available in the English language. The Licensed Software will be accompanied by a license key where required for activation and use of the Licensed Software. The Licensed Software shall also include, and this License Agreement shall govern the use of any update to the Licensed Software that Licensee receives pursuant to a separate support and/or maintenance purchase as described in Section 6 below, unless such update contains or comes with a different end user license agreement, in which case such end user license agreement shall supersede this License Agreement and govern the use of such software license without need for a mutually executed amendment to this License Agreement as set forth in Section 17 of this License Agreement. This License Agreement does not grant Licensee the right to any updates to the Licensed Software unless provided by Licensor under Section 6 and/or Section 7 below.

"Product Order" means a document that has been (i) executed by Licensee describing each Licensed Software license to be purchased, and (ii) accepted by Licensor. Licensor will accept the Product Order by either confirming Licensor's acceptance in writing or by delivering the Licensed Software to Licensee, whichever occurs first. A Product Order may also mean a written quote, or if referred to as such, a solution order, issued by Licensor describing each Licensed Software license purchased that is accepted by Licensee within the validity period of the quote either by Licensee executing and returning the quote or a solution order, to Licensor, by Licensee issuing a purchase order or other written confirmation of acceptance to Licensor in conformance with the quote, and/or by Licensee paying to Licensor all fees set forth in the quote. Each Product Order shall constitute a separate agreement and shall incorporate therein this License Agreement. In the event of any conflict between the terms and conditions of this License Agreement and the terms and conditions of any Product Order, the conflicting terms and conditions of the Product Order shall govern. In no event shall any terms and conditions contained in a purchase order or similar document issued by Licensee in connection with this License Agreement or with a Product Order apply and any such document issued shall be only for the administrative purposes of identifying the Licensed Software ordered, the number of licenses, and the price to be paid and shall have no other legal effect. Licensor for purposes of this paragraph shall mean Licensor or, if applicable, one of Licensor's authorized resellers from whom Licensee purchases the Licensed Software, provided however that any conflicting or additional terms in a Product Order accepted by an authorized reseller of Licensor shall have no effect unless such terms have been agreed by Licensor in writing.

"Warranty Period" means a period of ninety (90) days from delivery of the Licensed Software to Licensee.

  1. GRANT OF LICENSE; LICENSE CONDITIONS. For payment of the applicable non-refundable license fees identified on the Product Order and subject to Licensee's compliance with the terms and conditions set forth in this License Agreement, Licensor grants solely to Licensee, as an end user, a personal, perpetual (unless a subscription/term license has been purchased by Licensee), non-transferable, non-sublicensable and non?exclusive license to use the Licensed Software solely for its own internal use and benefit. Licensee's use and operation of the Licensed Software and the license grant provided to the Licensed Software is subject to Licensee being in possession of a valid license key where required for the Licensed Software to run. Licensee agrees that Licensor is not liable or responsible for lost or broken license keys or media or the provision of replacement license keys or media and/or new license keys or media unless Licensee is current on support and maintenance for the applicable license and then only to the extent set forth in the applicable annual support and/or maintenance agreement and only to the extent Licensor then has sufficient rights from any applicable third party suppliers, if necessary, to provide such replacement. If not current on support and maintenance for the applicable license, replacement or new license keys or media may be available for purchase at Licensor's then current list fees for applicable new licenses.

    Different License Options are available from Licensor as set forth or referred to in Annex 1. The applicable License Option and license count to be purchased by Licensee for the Licensed Software shall be identified in the Product Order or otherwise identified in writing by Licensor. Licensed Software is also subject to additional terms and conditions as set forth in the "Specific Software Terms" located in Annex 2. Any conflicting terms and conditions shall be resolved according to the following order of precedence: Annex 2, Annex 1, and the main body of the License Agreement.

  2. USE RESTRICTIONS. Except as may be otherwise specifically permitted in Annex 1 or Annex 2 to this License Agreement, Licensee agrees not to:
    • 2.1 Copy and/or distribute the Licensed Software, in whole or in part, for internal use without paying Licensor the applicable additional fees required by Licensor, except (i) for making a reasonable number of archival back-up copies; or (ii) as expressly authorized by Licensor in writing; or (iii) for making a reasonable number of copies of the Documentation supplied to Licensee by Licensor in electronic form. Licensee shall reproduce and affix all copyright and other proprietary rights notices appearing in or on the Licensed Software, including notices of all third party suppliers.
    • 2.2 Use the Licensed Software for timesharing, facilities management, outsourcing, hosting, service bureau use, or for providing other application service (ASP) or data processing services to third parties or for like purposes.
    • 2.3 Modify the Licensed Software or provide any person with the means to do the same.
    • 2.4 Create derivative works of the Licensed Software, or translate, disassemble, recompile or reverse engineer the Licensed Software or attempt to do so (except to the extent applicable law specifically permits such activity).
    • 2.5 Alter, destroy, or otherwise remove any proprietary notices or labels on or embedded within the Licensed Software or Documentation.
    • 2.6 Use the Licensed Software in a manner other than as specifically permitted in this License Agreement.
  3. AUDITS. Licensor or an Auditor (as defined below) has the right to verify Licensee's compliance with this License Agreement (and please see Micro Focus License Compliance Charter - http://supportline.microfocus.com/licensing/licVerification.aspx). Licensee agrees to:
    • A. Implement internal safeguards to prevent any unauthorized copying, distribution, installation, or use of, or access to, the Licensed Software and associated support and maintenance, or breach of the terms or conditions of this License Agreement;
    • B. Take all necessary steps to destroy or erase all Licensed Software codes, programs and other proprietary information before disposing of any media containing the Licensed Software;
    • C. Keep records sufficient to certify Licensee's compliance with this License Agreement including serial numbers and license keys of the Licensed Software, hypervisor logs where applicable, and the location, model (including quantity and type of processor) and serial number of all machines on which the Licensed Software is installed or from which the Licensed Software is accessed, and the names (including corporate entity) and number of users that are accessing the Licensed Software, and, upon request of Licensor, provide and certify metrics and/or reports based upon such records and account for, among other things, numbers of copies (by product and version) and network architectures as they may reasonably relate to Licensee's licensing and deployment of the Licensed Software and associated support and maintenance;
    • D. Upon Licensor's request, Licensee shall furnish Licensor or an independent auditor chosen at Licensor's sole discretion ("Auditor"), within seven (7) days of the request, with a completed questionnaire provided by Licensor or the Auditor, and with a written statement, in a format required by Licensor, signed by a director of Licensee, certifying the accuracy of any information provided;
    • E. Allow a Licensor representative or an Auditor to inspect and audit Licensee's computers and records, during Licensee's normal business hours, for compliance with the licensing terms for Licensor's software products and associated maintenance. Upon Licensor's (and Auditor's if applicable) presentation of their signed written confidentiality statement form, Licensee shall fully cooperate with such audit and provide any necessary assistance and access to records and computers; and
    • F. In the event that Licensee has or at any time has had unlicensed installation, use of, or access to the Licensed Software or has otherwise breached the license granted (a "Non-Compliance"), without prejudice to any other rights or remedies Licensor may have, including without limitation injunctive relief, Licensee shall, within thirty (30) days, purchase sufficient licenses and or subscriptions and associated support and maintenance to cure the Non-Compliance, without benefit of any otherwise applicable discount, by paying Licensor's current (as of the date of such additional purchase) list license fees and 12-month support and maintenance fees to Licensor for such additional licenses, plus Licensor's current (as of the date of such additional purchase) list term license and support and maintenance fees and interest (compounded at 1.5% monthly or the maximum rate permitted by applicable law if lower) for such additional licenses for the time period from the commencement of the Non-Compliance until payment of the aforementioned fees. The aforementioned interest shall be payable even if an invoice was not issued at the time the Non-Compliance commenced. If a material license shortfall of 5% or more is found, Licensee shall also reimburse Licensor for the reasonable cost of such audit in addition to other amounts due. The obligations in this Section 3 shall apply to both Licensee's Non-Compliance and any third party's Non-Compliance.
  4. DOCUMENTATION. One (1) electronic copy of Licensor's standard Documentation, describing Licensor's recommended use and application of the Licensed Software, will be furnished or made available on Licensor's website free of additional charge to Licensee by Licensor with the Licensed Software. Printed copies of any Documentation may be available for purchase from Licensor or its authorized distributors. Additional copies of standard Documentation may be available on Licensor's website.
  5. TERM OF LICENSE. This License Agreement and Licensee's license for the Licensed Software is perpetual, unless a subscription/term license has been purchased by Licensee (in which case the term of the license shall be as set forth in the Product Order, specified in Annex 1 or Annex 2, or as otherwise agreed in writing between the Licensee and Licensor), and is subject to earlier termination as provided in this Section 5. If Licensee has purchased a subscription/term license, Licensee's license to the Licensed Software shall automatically terminate upon expiry of such subscription/term. Licensor may terminate this License Agreement and Licensee's license to the Licensed Software immediately by giving Licensee written notice of termination in the event that either (i) Licensee breaches any term or condition of this License Agreement and Licensee has failed to remedy such breach within ten (10) days of the date of notice from Licensor to Licensee or (ii) Licensee is wound up, has a receiver appointed or has applied for or enters into liquidation or bankruptcy or analogous process or processes. Termination shall be without prejudice to any other rights or remedies Licensor may have. In the event of any termination Licensee will have no right to keep, access, or use the Licensed Software or any copy of the Licensed Software for any purpose and Licensee shall destroy and erase all copies of such Licensed Software in its possession or control, and forward written certification to Licensor that all such copies of Licensed Software have been destroyed or erased. Termination shall not entitle the Licensee to any refund or reimbursement of any kind of previously paid fees. The rights and obligations of the parties contained in Sections 3, 8, 9, 10, 11, 12, and 13, and other sections that by their nature are intended to survive, will survive the termination or expiration of this License Agreement.
  6. SUPPORT AND MAINTENANCE. Where Licensee purchases support and/or maintenance services, Licensee's initial support and/or maintenance term will begin upon delivery to Licensee of the Licensed Software and continue for one (1) year thereafter (or the length of the term if less than a year for any subscription/term license) unless otherwise specified in the applicable annual support and/or maintenance agreement, Product Order, or other written agreement executed between Licensor and Licensee. Where Licensee purchases support and/or maintenance for any Licensed Software, Licensee hereby agrees that it shall purchase such support and/or maintenance services for all of Licensee's licensed units of such Licensed Software product. Support and/or maintenance services provided by Licensor will be subject to Licensor's then current applicable standard annual support and/or maintenance agreement unless otherwise agreed by the parties in writing.
  7. LIMITED WARRANTY. Licensor warrants for the Warranty Period (i) that if the Licensed Software is supplied via media, then the media will be free from defects in materials or workmanship under normal use and (ii) that the copy of the Licensed Software delivered to Licensee conforms in all material respects to the Documentation. As the sole and exclusive remedy for not meeting part (i) of the above warranty, Licensor's sole obligation shall be to repair or replace free of charge any defective media on which the Licensed Software is delivered if the media is returned to Licensor by Licensee during the Warranty Period. As the sole and exclusive remedy for not meeting part (ii) of the above warranty, Licensor shall repair or replace the Licensed Software free of charge so that it conforms with the warranty or, if Licensor reasonably determines that such remedy is not economically or technically feasible, Licensee shall be entitled to a full refund of the license fee and any maintenance fee paid by Licensee with respect to that particular Licensed Software. Upon such refund Licensee's license to use such Licensed Software will terminate. The warranty set forth in this Section 7 shall not apply if the defect in the Licensed Software is the result of: (a) the Licensed Software not being used in accordance with the Documentation, this License Agreement or with the platform(s) for which the Licensed Software has been designed and licensed by Licensor; or (b) the Licensed Software having been altered, modified or converted by Licensee or any third party except as may be specified in the Documentation; or (c) the malfunctioning of Licensee's equipment; or (d) accident or abuse; or (e) service by any unauthorized person; or (f) other software used by Licensee which has not been provided by Licensor or for which the Licensed Software is not designed and licensed for operation; or (g) Third Party Software (as defined herein); or (h) any other cause occurring after initial delivery of the media to Licensee unless caused directly by Licensor. The foregoing states the complete and entire remedies that Licensee has under this warranty. Licensor shall have no responsibility for any warranty claims made outside of the Warranty Period. The foregoing warranty shall not apply to any free-of-charge Licensed Software including updates, though issues with such software may be eligible for support under applicable support terms and conditions.
  8. DISCLAIMER OF WARRANTY. The Licensed Software cannot be tested in every possible operating environment, therefore Licensor does not warrant that the functions contained in the Licensed Software will meet Licensee's requirements, that operation of the Licensed Software will be uninterrupted, or that the Licensed Software is error free. EXCEPT AS SET FORTH HEREIN AND TO THE EXTENT PERMITTED BY LAW, ALL OTHER WARRANTIES, EXPRESSED OR IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, QUALITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE EXCLUDED ON THE PART OF LICENSOR AND ITS THIRD-PARTY SUPPLIERS. Licensee acknowledges that Licensee is responsible for the selection of the Licensed Software to achieve Licensee's intended results and for the installation and/or use of, and results obtained from, the Licensed Software.
  9. LIMITATION OF LIABILITY. ANY LIABILITY OF LICENSOR SHALL BE LIMITED IN THE AGGREGATE TO THE AMOUNTS PAID BY LICENSEE FOR THE LICENSED SOFTWARE GIVING RISE TO THE APPLICABLE CLAIM. THIS LIMITATION APPLIES TO ALL CAUSES OF ACTION, INCLUDING WITHOUT LIMITATION BREACH OF CONTRACT, BREACH OF WARRANTY, NEGLIGENCE, STRICT LIABILITY, MISREPRESENTATION AND OTHER TORTS. IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR SIMILAR DAMAGES NOR FOR ANY LOSS OF PROFITS, CONTRACTS, DATA, OR PROGRAMS, OR THE COST OF RECOVERING SUCH DATA OR PROGRAMS, EVEN IF INFORMED OF THE POSSIBILITY OF SUCH DAMAGES IN ADVANCE. LICENSOR’S LIMITATIONS OF LIABILITY ARE NOT CUMULATIVE. LICENSEE’S REMEDIES IN THIS LICENSE AGREEMENT ARE LICENSEE’S EXCLUSIVE REMEDIES.

    NONE OF LICENSOR’S THIRD-PARTY SUPPLIERS SHALL BE LIABLE FOR ANY INJURY, LOSS OR DAMAGE, WHETHER DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL NOR FOR ANY LOSS OF PROFITS, CONTRACTS, DATA, OR PROGRAMS, OR THE COST OF RECOVERING SUCH DATA OR PROGRAMS, EVEN IF INFORMED OF THE POSSIBILITY OF SUCH DAMAGES IN ADVANCE.

    LICENSEE AGREES THAT, IN ENTERING INTO THIS LICENSE AGREEMENT, EITHER IT DID NOT RELY ON ANY REPRESENTATIONS (WHETHER WRITTEN OR ORAL) OF ANY KIND OTHER THAN THOSE EXPRESSLY SET OUT IN THIS LICENSE AGREEMENT, OR IF IT DID RELY ON ANY REPRESENTATIONS, THAT IT SHALL HAVE NO REMEDY AGAINST LICENSOR IN RESPECT OF SUCH REPRESENTATIONS.

    LICENSEE FURTHER ACKNOWLEDGES THAT THE LIMITATIONS OF LIABILITY IN THIS SECTION ARE AN ESSENTIAL ELEMENT OF THIS LICENSE AGREEMENT AND THAT, IN THE ABSENCE OF SUCH LIMITATIONS, THE PRICING AND OTHER TERMS AND CONDITIONS SET FORTH HEREIN WOULD BE SUBSTANTIALLY DIFFERENT.

    NEITHER THIS LICENSE AGREEMENT NOR ANYTHING IN THIS SECTION 9 SHALL EXCLUDE OR RESTRICT THE LIABILITY OF LICENSOR OR ITS THIRD-PARTY SUPPLIERS TO ANY EXTENT NOT PERMITTED BY LAW.

  10. HIGH-RISK USES. The Licensed Software is not fault tolerant, nor designed, manufactured or intended for use in hazardous environments requiring fail-safe performance (including, without limitation, the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, direct life support machines, or weapons systems) in which failure of the Licensed Software could lead directly or indirectly to death, personal injury or severe physical or environmental damage. Licensor and its suppliers shall have no liability for any use of the Licensed Software in any high-risk situations.
  11. OWNERSHIP. Licensor (or its affiliates) and where applicable Licensor's third party suppliers have and will retain all ownership rights to the Licensed Software, together with any complete or partial copies thereof. Such ownership rights include without limitation all patent rights, copyrights, trademarks, trade secrets, service marks, related goodwill, and confidential and proprietary information relating thereto. This License Agreement does not convey any proprietary interest to Licensee with respect to the Licensed Software other than the license specified herein.
  12. THIRD PARTY SOFTWARE AND COMPONENTS. The Licensed Software may come with and/or require certain named third party software programs that Licensee shall license directly from the third party subject to such third party's terms and conditions (for example Adobe Acrobat or Microsoft Internet Explorer) ("Third Party Software"). Any Third Party Software is provided by the licensor of the Third Party Software solely under a direct license between such third party and Licensee under such third party's terms and conditions. Therefore the obligations, duties and rights of Licensor and Licensee under this License Agreement do not apply to such Third Party Software. Additionally, Licensor has embedded in some Licensed Software certain run time or other elements provided by third party suppliers to Licensor ("Third Party Components"). Such Third Party Components may also be loaded on the Licensed Software media. Third Party Components are licensed to Licensee pursuant to this License Agreement. Third Party Components may also include open source software, details of which (where applicable) may be found (i) in a file accompanying the applicable Licensed Software or (ii) in the applicable Documentation. Licensee may only access Third Party Components of the Licensed Software in the course of using the Licensed Software. Licensee may not make or attempt any direct access to any such Third Party Components other than with the Licensed Software. All limitations, restrictions and obligations applicable to the Licensed Software set forth in this License Agreement shall apply to Licensee's use of the Third Party Components. The Third Party Software and Third Party Components are the property of its respective third party supplier to Licensor. Such third party suppliers own all copies of the Third Party Software and Third Party Components, however made. Licensee agrees not to contest the ownership of the Third Party Software and Third Party Components nor use any trademark or service mark belonging to such third party suppliers. Licensee agrees that such third party suppliers are intended third party beneficiaries of all terms and conditions of this License Agreement intended to protect intellectual property rights in the Licensed Software (including the Third Party Components) and limit certain uses thereof. Nothing in this License Agreement shall restrict, limit or otherwise affect any rights or obligations Licensee may have, or conditions to which Licensee may be subject, under any applicable open source licenses to any open source code contained in the Licensed Software.
  13. NOTICE TO U.S. GOVERNMENT END USERS. The Licensed Software and Documentation are deemed to be "Commercial Items," as defined at 48 C.F.R. §2.101, consisting of "Commercial Computer Software" and "Commercial Computer Software Documentation," as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7207, as applicable. Consistent with such sections, the Licensed Software and Documentation are licensed to U.S. Government end users (i) only as Commercial Items, and (ii) with only those rights as are granted pursuant to this License Agreement. Manufacturer is Micro Focus (US), Inc., 700 King Farm Blvd., Suite 125, Rockville, MD 20850 as or on behalf of Licensor.
  14. LICENSE FEES AND PAYMENT TERMS. Licensee agrees to pay the applicable end user license fees for the Licensed Software within thirty (30) days of the date of invoice or such other date as agreed in writing by the parties. End user license fees are non-refundable except as provided in Section 7 above, or in the Specific Software Terms below, and shall be paid without deduction, including without limitation, of any withholding tax. End user license fees are exclusive of any applicable transportation charges, value added and other applicable taxes and duties and all such amounts shall be paid or reimbursed by Licensee. Outstanding past-due amounts shall accrue interest at the rate of 1.5% per month compounded or, if lower, the maximum rate allowed by applicable law. Licensee shall be liable for any such interest and all related collection costs, whether or not an action has been filed. Licensor may decline to enter into any additional Product Orders if any such past-due balance, interest and collection costs are not paid.
  15. RELATED SERVICES. Licensee shall be responsible for obtaining and installing all proper hardware and support software (including operating systems) and for proper installation and implementation of and training concerning the Licensed Software. In the event that Licensee retains Licensor to perform any services with respect to the Licensed Software (for example: installation, implementation, maintenance, consulting and/or training services), Licensee and Licensor agree that such services shall be subject to Licensor's then current standard terms, conditions and rates for such services unless otherwise agreed in writing by Licensor.
  16. PRIVACY. If the Licensed Software contains features that may allow Licensee to collect data from, control and/or monitor computers running the Licensed Software deployed by Licensee without notice to or knowledge by users of the Licensed Software, then: (i) Licensee is solely responsible for, and assumes all liability with respect to, the collection of data with respect to its users of the Licensed Software including, without limitation, notifying such users and complying with all data collection, privacy and other regulations, laws, industry standards and rights of others applicable to any such activity; and (ii) Licensee shall indemnify and hold Licensor harmless from and against any damages, claims, losses, settlements, attorneys' fees, legal fees and court costs and other expenses related to any such activities or any claims in connection therewith. To the extent permitted by law, by entering into this License Agreement, Licensee hereby expressly consents to (i) Licensor sending information to Licensee from time to time advertising the various products that Licensor provides, whether or not such products are provided under this License Agreement; (ii) the use of Licensee's name in Licensor customer lists, promotional materials and/or press releases; and (iii) the collection and use by Licensor of information about the computer system on which the Licensed Software is installed (e.g. product version, serial number) for internal security and licensing purposes; Licensor does not use this information to identify individuals utilizing such software.
  17. MISCELLANEOUS. Licensor may assign this License Agreement (in whole or in part) to any member of Licensor's group of companies or to a purchaser of the intellectual property rights in the Licensed Software, but otherwise neither this License Agreement nor any rights hereunder may be assigned (any change of control merger, sale or other transfer of all, or substantially all, of the assets of Licensee shall be included in the meaning of an assignment) nor duties delegated by either party, and any attempt to do so will be void.

    If Licensee acquires the Licensed Software in North America, the laws of the state of Maryland govern this License Agreement and the licenses granted hereunder and the parties hereto consent and agree that they shall be subject to the exclusive jurisdiction of the State and/or Federal courts sitting in the State of Maryland in any action based on this License Agreement or concerning the licenses granted, or the products licensed, hereunder. Each party waives any right it may have to object to such venue, including objections based on personal jurisdiction or forum non conveniens (inconvenient forum). The parties agree that the Uniform Computer Information Transaction Act or any version thereof, adopted by any state, in any form ("UCITA"), shall not apply to this License Agreement. To the extent that UCITA is applicable, the parties hereby opt out of the applicability of UCITA pursuant to the opt-out provision(s) contained therein. If Licensee acquires the Licensed Software in France, Germany or Japan, this License Agreement is governed by the laws of the country in which Licensee acquired the Licensed Software. In the rest of the world the laws of England govern this License Agreement. The aforesaid applicable law shall apply without regard to conflicts of laws provisions thereof, and without regard to the United Nations Convention on the International Sale of Goods. Other than for North American transactions, this License Agreement, the licenses granted hereunder, and the parties hereto, shall be subject to the exclusive jurisdiction of the courts of the country determining the applicable law as aforesaid. In the event of a dispute, the prevailing party shall have the right to collect from the other party its reasonable costs and necessary disbursements and attorneys' fees incurred in enforcing this License Agreement.

    This License Agreement is in addition subject to any United States, United Kingdom or European Union laws, regulations and other restrictions regarding export or re-export of computer software and technology. Licensee agrees not to export or re-export any Licensed Software or derivative thereof in contradiction to any such applicable restriction. In particular but without limitation, Licensee acknowledges that Licensor's products and/or technology are subject to the U.S. Export Administration Regulations (the "EAR") and Licensee agrees to comply with the EAR. Licensee will not export or re-export Licensor's products, directly or indirectly, to: (1) any countries that are subject to US or applicable export restrictions; (2) any end user who Licensee knows or has reason to know will utilize Licensor's products in the design, development or production of nuclear, chemical or biological weapons, or rocket systems, space launch vehicles, and sounding rockets, or unmanned air vehicle systems; or (3) any end user who has been prohibited from participating in export transactions by any applicable agency of government. By downloading or using the Licensed Software, Licensee is agreeing to the foregoing and Licensee is representing and warranting that Licensee is not located in, under the control of, or a national or resident of any such country or on any such list.

    Licensor may identify Licensee by name and/or logo as a licensee of Licensor for investor relations, analyst relations, and public relations purposes, and in online and printed sales and marketing materials. Any other use of Licensee's name or logo, or a description of Licensee's use of the Licensed Software, shall be subject to Licensee's prior consent. Within eight (8) weeks after installation of the Licensed Software, upon Licensor's written request Licensee will provide Licensor with input to a written description of Licensee's use of the Licensed Software including details of the business challenge, software solution, and results realised from the installation of the Licensed Software. The input shall be provided by a representative of Licensee (who is knowledgeable of the Licensed Software and its performance after installation) during a meeting with a representative of Licensor (at a reasonable time to be agreed by the parties). The meeting may be conducted by telephone. This input may be used internally within Licensor and in confidential sales situations. Any other use of this input shall be subject to Licensee's prior consent.

    Except for the Product Order, this License Agreement is the complete and exclusive statement of agreement between the parties relating to the license for the Licensed Software and supersedes all proposals, communications, purchase orders, and prior agreements, verbal or written, including without limitation prior end user license agreements in relation to the Licensed Software between the parties and end user license agreements embedded in such Licensed Software. No employee, agent, or representative of Licensor has the authority to bind Licensor to any oral representation or warranty concerning the Licensed Software. No representation or statement not expressly contained in this License Agreement nor any supplement, modification, or amendment of this License Agreement will be binding on either party unless executed in writing by a duly authorized representative of Licensor and Licensee (excluding any distributor or reseller of Licensor) to this License Agreement. No waiver of any right under this License Agreement will be effective unless in writing, signed by a duly authorized representative of the party to be bound (excluding any distributor or reseller of Licensor). No waiver of any past or present right arising from any breach or failure to perform will be deemed to be a waiver of any future right arising under this License Agreement. If any provision in this License Agreement is invalid or unenforceable, that provision will be construed, limited, modified or, if necessary, severed, to the extent necessary, to eliminate its invalidity or unenforceability, and the other provisions of this License Agreement will remain unaffected. Each party acknowledges that in entering into this License Agreement it has not relied on any representations, agreements, warranties or other assurances (other than those repeated in this License Agreement and the Product Order) and waives all rights and remedies which but for this section 17 would be available to it. Nothing in this section 17 excludes liability for fraudulent misrepresentation.

    If Licensee is situated in Italy, by placing or executing a Product Order, Licensee declares to have read and to have explicitly approved the following clauses of the License Agreement: 5. Term of License, 6. Support and Maintenance, 7. Limited Warranty, 8. Disclaimer of Warranty, 9. Limitation of Liability, 10. High-Risk Uses, 16. Privacy, 17. Miscellaneous, Annex 1, and Annex 2.

ANNEX 1, LICENSE OPTIONS

DEFINITIONS

For this License Agreement, the following additional definitions shall apply:

"Batch Processing" means the execution of one or more tasks, transactions or programs by a computer system without the continuous interaction of the end user with the Licensed Software for the entire period during which each such task, transaction or program is being executed by the system. Batch processing includes situations where a queue of jobs is processed as resources become available and is in contrast to transaction or interactive processing.

"Blades" means multiple server modules housed in a single chassis each with its own CPU, hard disk and memory.

"Container" means an isolated user-space instance created using operating-system-level virtualization, also known as containerization. A program running inside a Container can only see the resources and devices assigned to the Container.

"Core" means a physical (not virtual) subunit within a CPU on a single chip that handles the main computational activities of a computer. A CPU may have one or more Cores and therefore be a "Multicore CPU" if it has more than one Core.

"CPU" (Central Processor Unit) means a data processing unit, normally identified with a single microchip mounted on a single circuit board and can comprise several Cores.

"Hard Partitioning" means using hard physical partitioning to physically segment a single larger server or machine into separate and distinct smaller systems where each separate system acts as a physically independent, self-contained server or machine with its own CPUs, operating system, separate boot area, memory, input/output subsystem and network resources (each known as a "Hard Partition"). Examples of Hard Partitioning methods include: Physical Domains (also known as PDomains, Dynamic Domains or Dynamic System Domains), Solaris Zones (also known as Solaris Containers, capped Zones/Containers only), LPAR (adds DLPAR with AIX 5.2), Micro-Partitions (capped partitions only), vPar, nPar, Integrity Virtual Machine (capped partitions only), Secure Resource Partitions (capped partitions only), and Fujitsu’s PPAR.

"Platform" means a hardware chipset (e.g., PA-RISC, Itanium, x86, or SPARC) and operating system (e.g., Windows, Linux, Solaris, AIX, or HP-UX) combination.

"Soft Partitioning" means using an operating system resource manager to segment and limit the number of Cores, CPUs, or other processing devices utilized by the Licensed Software by creating areas where processor resources are allocated and limited within the same operating system (each such area known as a "Soft Partition"). Examples of such Soft Partitioning include: Solaris 9 Resource Containers, AIX Workload Manager, HP Process Resource Manager, Affinity Management, Oracle VM, VMware, and Partition Relocation (such as IBM Power VM Live Partition Mobility).

"Update" means the definition for such term set forth in Licensor's then current applicable standard annual support and/or maintenance agreement.

"Upgrade" means any change in the licensed Platform for the Licensed Software or a successor product to the Licensed Software.

"Virtual Machine" means a software implementation that can run its own operating system and execute programs like a physical machine where the software running inside the virtual machine is limited to the resources and abstractions provided by the virtual machine.

LICENSE OPTIONS

  1. Development License Options (Enterprise Developer and Visual COBOL only)
    1. Named User License. Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on a single machine or server, or one or more Containers on such single machine or server, for use solely by the number of named users expressly authorized by Licensor in the Product Order for whom Licensee has paid the applicable license fee . A named user must only be one named person and such named person has the right to unlimited access to the Licensed Software on such single machine or server. A Named User License is not based on concurrent users, but instead on an actual named user basis. Licensor reserves the right at any time to require Licensee to provide a list of the named users. Licensee may change a named end user provided that the change is made either (i) permanently, or (ii) temporarily to accommodate the use of the Licensed Software by a temporary worker while the named user is absent, but in each case no more than once every 30 days. Licensee may not use the Licensed Software for user acceptance testing, system/load testing, production or deployment.
    2. Concurrent User License. Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on multiple host machines or servers, or one or more Containers on such host machines or servers, for use solely by the maximum number of concurrent users expressly authorized by Licensor in the Product Order for whom Licensee has paid the applicable license fee. Concurrent users are individuals who are actively using any device or other software program that may access the Licensed Software either directly, or indirectly through any other software program, regardless of how such access occurs or if such user uses any hardware or software that reduces the apparent number of users who are using the Licensed Software, such as by using a terminal service. Licensee may not use the Licensed Software for user acceptance testing, system/load testing, production or deployment.
  2. Deployment License Options (Enterprise Server, Enterprise Server for .NET, Enterprise Test Server, Enterprise Test Server Premium, COBOL Server, and Database Connectors)
    1. User License Option (COBOL Server only).

      User License for Authorized Users. Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on an unlimited number of servers or Containers for use by up to the total number of named individuals for whom Licensee has paid the applicable license fee. The Licensed Software may not be used or accessed by (i) individuals who are not named individuals; or (ii) any other software or hardware device that does not require a named individual to use or access it. A named individual means an individual identified by Licensee by name who is authorized to use any device or other software program that may access the Licensed Software, either directly or indirectly through any other software program, regardless of how such access occurs or if such individual uses any hardware or software that reduces the apparent number of users who are using the Licensed Software, such as by using a terminal service. The Licensed Software may not be used or accessed by any other software or hardware device that does not require an individual to use or access it including, without limitation, Batch Processing. Licensor reserves the right at any time to require Licensee to provide a list of the named individual(s). Licensee may change a named individual provided that the change is made either permanently away from the named individual or temporarily to accommodate the use of the Licensed Software by a temporary worker while the named individual is absent, but in no event more than once every 30 days.

    2. Server License Options. There are two options for server-based licenses. Please note that server-based licenses may only be installed on one machine or server or one or more Containers on such single machine or server. Additional licenses are therefore required to be purchased by Licensee for use of the Licensed Software on more than one machine for any purpose, including disaster recovery, load-balancing, clustering, fail-over, training, or testing. Licensed Software may be licensed solely for evaluation, disaster recovery, fail-over, training, or testing purposes and in such case will be subject to the applicable License Option terms and conditions set forth in this Annex 1.

      (i) Server License for Concurrent Users (COBOL Server and Database Connectors only). Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on a single machine or server, or one or more Containers on such single machine or server, for use by the maximum number of Concurrent Users for whom Licensee has paid the applicable license fee. Concurrent Users are individuals who are actively using any device or other software program that may access the Licensed Software either directly, or indirectly through any other software program, regardless of how such access occurs or if such user uses any hardware or software that reduces the apparent number of users who are using the Licensed Software, such as by using a terminal service. The Licensed Software may not be used or accessed by any other software or hardware device that does not require an individual to use or access it including, without limitation, Batch Processing. Licensee may only use the Licensed Software on or access the Licensed Software from one server at any one time. Subject to the prior written consent of Licensor and to payment of additional license fees, Licensee may permit the public and/or Licensee's customers to access and use the Licensed Software via the internet and/or Licensee's terminals in connection with Licensee's internal business purposes (for example to access internet banking from Licensee) but not for the public's and/or Licensee's customers' own internal use.

      (ii) Server License for CPUs. Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on a single machine or server ("Host Server"), or one or more Containers on the Host Server, and have the Licensed Software executed by up to the total number of CPUs, Cores, Integrated Facility for Linux processors ("IFLs"), Blades or other processing devices specified for the license in the applicable Product Order ("License Specification"). If the number of Cores is not specified for a CPU in the event a CPU is specified in the License Specification, such CPU shall be considered to be single-Core. A Server License for CPUs license covering all CPUs, Cores, IFLs, Blades and other processing devices that are contained in and/or can be accessed by the Host Server ("Total Processors") is required with all applicable license fees paid, even if one or more of such CPUs, Cores, IFLs, Blades or other processing devices are not accessing or running the Licensed Software. For example, if 32 Cores are the Total Processors on the Host Server, but only 16 Cores are utilized to execute the Licensed Software, a 32-Core Server License for CPUs license is required notwithstanding the fact that 16 of the 32 Cores may not actually be accessing the Licensed Software. Each Core on a multi-core CPU requires a Server License for CPUs license covering each such Core. For example a Host Server with Total Processors consisting of a single quad-core CPU will require a 4-Core Server License for CPUs license and payment of the license fees applicable to all 4 Cores.

      The Licensed Software is for use by an unlimited number of Licensee's internal users, other software devices and hardware devices. A Server License for CPUs is the only license authorized for use or access by Licensee for any Batch Processing. Licensor reserves the right at any time to require Licensee to provide a specification of the Host Server. Licensee may change the designated Host Server provided that the new Host Server's specifications are authorized under the applicable Server License for CPUs license, including, but not limited to, the Total Processors in, and thus the Server License for CPUs licenses required for, the new Host Server do not exceed the License Specification(s) for the Server License for CPUs license(s) used for the old Host Server plus any new Server License for CPUs license(s) purchased by Licensee for use on the new Host Server. Licensee is required to purchase a license for the Total Processors on each Host Server that accesses or uses the Licensed Software either directly or indirectly through any other software program, regardless of how such access occurs, or if the Host Server, CPU or operator uses any hardware or software that reduces the apparent number of CPU, Cores, IFLs, Blades or other processing devices that are using the Licensed Software, such as by using a terminal service. Subject to the prior written consent of Licensor and to payment of additional license fees, Licensee may permit the public and/or Licensee's customers to access and use the Licensed Software via the internet and/or Licensee's terminals in connection with Licensee's internal business purposes (for example to access internet banking from Licensee) but not for the public's and/or Licensee's customers' own internal use.

    3. Test License Option Licensed Software provided under this License Option gives Licensee a limited license to use the Licensed Software solely for Licensee's internal testing purposes on a single computer system subject to this section and the restrictions applicable to the type of license purchased as specified in the applicable Product Order (e.g., User License for Authorized Users, Server License for CPUs, etc.). In the event of a conflict, the terms and conditions in this section shall prevail. At no time may Licensee use the Licensed Software for development, commercial, or production purposes, nor may Licensee reproduce or distribute the Licensed Software or any software application programs created with it. Licensee's results of benchmark or other performance tests run on or using the Licensed Software may not be disclosed to any third party without Licensor's prior written consent. If Licensee uses the Test Licenses for any purpose other than for Licensee's internal testing purposes, the Test License shall terminate automatically and without notice. Upon such termination, Licensee may convert the terminated Test License to a standard license type listed above by paying the applicable conversion fee. In relation to Licensed Software provided pursuant to this Test License Option, this Section shall prevail over any contrary provisions set forth in this License Agreement. For the avoidance of doubt, a "test" license as described above is not a license to use Licensor's software quality or "testing" products, however such products may be available under this Test License Option.
    4. Disaster Recovery License Option Licensed Software provided under this License Option gives Licensee a limited license to use the Licensed Software solely on a Cold Disaster Recovery System subject to this section and the restrictions applicable to the type of license purchased as specified in the applicable Product Order (e.g., User License for Authorized Users, Server License for CPUs, etc.). In the event of a conflict, the terms and conditions in this section shall prevail. A Cold Disaster Recovery System is a computer system that is used only (i) if a disaster arises and the original production, test, or development system is unavailable, (ii) for the purposes of disaster recovery testing and/or (iii) for system diagnostics or maintenance of the Cold Disaster Recovery System itself. Licensed Software provided under this option cannot be used (a) concurrently with any Deployment License for the Licensed Software except while the original production, test, or development system is being recovered; (b) in production, test, or development environments except in a disaster recovery situation: or (c) for load-balancing, failover, testing (other than disaster recovery testing), clustering, or training purposes. Additional copies for use in production, test, and/or development environments, or for load-balancing, failover, clustering, or training purposes, or for installation in any computer system that is in use must be purchased separately. Cold Disaster Recovery Licenses shall terminate automatically without notice if the Licensed Software provided under this License Option is installed on anything other than a Cold Disaster Recovery System, if Licensee ceases to use the Licensed Software for disaster recovery purposes, or if Licensee is otherwise in violation of the restrictions set forth in this section.
    5. Failover License Option Licensed Software provided under this License Option gives Licensee a limited license to use the Licensed Software solely on a single standby failover server in standby, non-production mode subject to this section and the restrictions applicable to the type of license purchased as specified in the applicable Product Order (e.g., User License for Authorized Users, Server License for CPUs, etc.). In the event of a conflict, the terms and conditions in this section shall prevail. Licensee may not use the Licensed Software for production, testing (other than failover testing), development, or training except during periods when one or more copies of the Licensed Software for which Licensee has purchased a Deployment License are nonfunctional. Licensee may not use the Licensed Software for load-balancing or clustering, for which a separate license is required to be purchased by Licensee.
    6. Training License Option Licensed Software provided under this License Option gives Licensee a limited license to use the Licensed Software solely for Licensee's internal training purposes on a single computer system subject to this section and the restrictions applicable to the type of license purchased as specified in the applicable Product Order (e.g., User License for Authorized Users, Server License for CPUs, etc.). In the event of a conflict, the terms and conditions in this section shall prevail. At no time may Licensee use the Licensed Software for development, testing, or production purposes, nor may Licensee reproduce or distribute the Licensed Software or any software application programs created with it.
  3. Evaluation License Option Licensed Software provided under this License Option gives Licensee a term license to use the Licensed Software within Licensee during the evaluation term specified in writing by Licensor, solely for evaluation and testing purposes on a single computer system and not for development, commercial, or production purposes. Licensee may not reproduce or distribute the Licensed Software. Licensee's results of benchmark or other performance tests run on or using the Licensed Software may not be disclosed to any third party without Licensor's prior written consent. At any time during the evaluation term or upon completion thereof, Licensee may, upon written notification to Licensor and payment of the applicable license fee, replace the evaluation license with a license to use the Licensed Software pursuant to one of the other applicable options listed in Annex 1. In the absence of such notification by Licensee, the evaluation license shall automatically terminate at the end of the evaluation term and Licensee shall return, or, if Licensor so directs, delete and destroy all such Licensed Software and provide Licensor with written confirmation of such deletion and destruction being completed. Licensor may, in its sole discretion, grant Licensee an extension to the evaluation term subject to receiving a written request and reasons for such request from Licensee prior to expiration of the evaluation term. Licensor will specify any such agreed extension in writing to Licensee. Licensed Software provided by Licensor free of license fee charge shall be deemed to be provided pursuant to this Evaluation License Option unless otherwise agreed in writing. In the absence of any contrary period specified in writing by Licensor, the evaluation term shall be deemed to be thirty (30) days. In relation to Licensed Software provided pursuant to this Evaluation License Option, this Section shall prevail over any contrary provisions set forth in this License Agreement.

ANNEX 2, SPECIFIC SOFTWARE TERMS

Additional Restrictions. Licensee agrees not to:

  1. Copy and/or distribute the Licensed Software, in whole or in part, to third parties, or use the Licensed Software for the benefit of any third party, or permit use or access by any third party to all or part of the Licensed Software without first paying Licensor any applicable additional fees required by Licensor and entering into a separate distribution license agreement with Licensor. For the avoidance of doubt, third party(ies) include without limitation contractors, outsourcers, Licensee's customers and the public.
  2. Transfer, ship or use the Licensed Software outside the continent in which it was originally licensed to Licensee without first paying Licensor any applicable additional fees required by Licensor. For purposes of the foregoing, "continent" shall mean North America, South America, Europe, Africa, Asia, Australia, or Antarctica.
  3. Install, access or use the Licensed Software on a Platform other than the Platform for which the Licensed Software was originally licensed to Licensee. Additional licenses for use of the Licensed Software on a Platform other than the one set forth in the applicable Product Order may be available upon payment of an additional license fee.
  4. Assign, sell, rent, lease, lend, sublicense, outsource or otherwise transfer the Licensed Software to any third party, or authorize or appoint any third party to do so, or otherwise allow a third party to directly or indirectly use or access the Licensed Software, without Licensee first paying Licensor the applicable additional fees required by Licensor.
  5. Install, use, or access the Licensed Software on, in, or from a Hard Partition, Soft Partition, or Virtual Machine, except in accordance with the Virtualization Rights clause below, or where Licensee is otherwise expressly authorized in each instance by Licensor in the applicable Product Order or otherwise in writing separate from this License Agreement (the "Authorization") which in each event will be subject to Licensee's payment to Licensor of additional applicable fees required by Licensor and Licensee's written confirmation to Licensor of Licensee's planned installation environment signed by a director or officer of Licensee (accompanied by all information as Licensor reasonably requires to verify). Except for licenses subject to the Virtualization Rights clause below, w here authorized in accordance with the foregoing and to the extent applicable to the subject license: (i) such Hard Partition, Soft Partition, or Virtual Machine, may only be tied to one physical machine and shall be considered the entire machine for licensing purposes ; and (ii) Licensee shall provide to Licensor, at such times as Licensor may reasonably request, confirmation that Licensee's computer systems comply with the applicable Authorization and the requirements of the License Agreement. Such confirmation shall be signed by a director or officer of Licensee and shall be accompanied by all information as Licensor reasonably requires to verify that Licensee is utilizing the Licensed Software in compliance with the terms and conditions of the License Agreement, including without limitation any relevant hypervisor logs. The foregoing is in addition to Licensor's rights under the Audits section of the License Agreement .
  6. Utilize any software application and/or program created, in whole or in part, with any Development License without first purchasing a valid and properly granted Deployment License.

Enterprise Developer, Visual COBOL. Licensee shall not use the Licensed Software, nor reproduce or distribute any files supplied as part of the Licensed Software, in order to create a compiler, interpreter, runtime support product or any other product that is generally competitive with or a substitute for the Licensed Software or any other Licensor product.

This Licensed Software may include or generate limited licenses for Enterprise Server, COBOL Server, or other application deployment product. If such licenses are included or generated, these limited licenses are provided solely for use by the licensed user(s) of the Licensed Software in order to unit test an application developed with the Licensed Software on the same machine or server used to develop the application and may not be used for system testing, production or deployment, and with respect to Visual COBOL may only be used if the Licensed Software is current on support and maintenance. Any use of this limited license outside of the development and unit testing of such applications is not permitted.

Enterprise Developer may come with Licensor's Rumba software, and in such event, Licensee may only use such copy of Rumba with Enterprise Developer on the same machine subject to the terms and conditions applicable to such Enterprise Developer license.

Enterprise Developer Connect. Licensee may install certain Enterprise Developer components and models in another Eclipse or IBM Developer for z environment in accordance with the applicable Documentation solely for use with a valid license for Enterprise Developer Connect.

Enterprise Server, Enterprise Server for .NET, Enterprise Test Server, Enterprise Test Server Premium, COBOL Server. With any valid and properly granted license to this Licensed Software, Licensee may reproduce and distribute internally, in whole or in part, subject to the applicable license option as described in Annex 1 and the applicable Product Order, any software application program created by Licensee using the corresponding development product for the Licensed Software (if separately licensed to Licensee by Micro Focus) ("Licensee Application Software"). In such event Licensee shall (a) include Licensor's copyright notice for the Licensed Software on any product label and as a part of any sign-on message for such Licensee Application Software product; and (b) indemnify, hold harmless and defend Licensor and its third-party suppliers from and against any claims or lawsuits, including attorneys' fees, legal fees and court costs that arise out of, or result from, the use or distribution of such Licensee Application Software.

Licensee can only reproduce and distribute Licensee Application Software to third parties after entering into a separate distribution agreement with Licensor. Usage and distribution of the Licensee Application Software arises both by the explicit distribution of any Licensee Application Software and by the implicit distribution and usage of any of the Licensee Application Software's functionality when linked into another software application program. Access and/or use of data, results and/or output obtained and/or generated, either directly or indirectly, and in any format whatsoever, through the use of any Licensed Software (such as when a user accesses an application that calls or uses output from another application running the Licensed Software, whether or not on the same machine or server) are deemed to be access and/or use of such Licensed Software. Licensor offers specific production licensing options for distribution to third parties which vary depending upon the license fees paid by Licensee and Licensee should contact its Licensor sales representative for more details.

Enterprise Test Server, Enterprise Test Server Premium. This Licensed Software may be used only for Licensee's internal testing purposes. At no time may Licensee use the Licensed Software for any production purpose.

Enterprise Developer Models. This Licensed Software may only be used with a valid license for Enterprise Developer and shall be governed by the same terms and conditions as such license. No support or maintenance is provided or available for this Licensed Software.

Virtualization Rights. Notwithstanding any language in this License Agreement to the contrary, with respect to a license for Enterprise Server, Enterprise Test Server, and COBOL Server, in the event the applicable Product Order specifies that such license includes "Virtualization Rights" in the line item for such license, then for as long as such license is current on support and maintenance with Licensor, Licensee may install, use, or access such license on, in, or from a single instance of the Licensed Software, or one or more Containers, within a single Virtual Machine that is not necessarily tied to just one physical machine. This Virtual Machine may not access more than the number of licensed physical Cores purchased (or virtual Cores provided that a virtual Core is equivalent to a physical Core). Such license may be installed on Licensee's owned and controlled premises or hosted off-premise by an external cloud provider. Licensee may make one (1) copy of the Virtual Machine in which the Licensed Software is installed and instantiate such Virtual Machine in the event and for as long as the primary installation is unavailable. Licensee shall provide to Licensor, at such times as Licensor may reasonably request, confirmation that the applicable computer systems comply with the foregoing and the requirements of the License Agreement. Such confirmation shall be signed by a director or officer of Licensee and shall be accompanied by all information as Licensor reasonably requires to verify that Licensee is utilizing the Licensed Software in compliance with the terms and conditions of the License Agreement, including without limitation any relevant hypervisor logs. The foregoing is in addition to Licensor's rights under the Audits section of the License Agreement. Upon any lapse in support and maintenance for the aforementioned license, such license will not enjoy the additional rights described in this clause.

Subscription and/or On-Demand License. Notwithstanding any language in this License Agreement to the contrary, with respect to a license for Visual COBOL, Enterprise Developer, Enterprise Server, Enterprise Test Server, and COBOL Server, in the event that the applicable Product Order specifies that such license is a Subscription and/or On-Demand license, such license will be subject to a separate written agreement signed by Licensor and Licensee setting forth additional terms and conditions specific to Subscription and/or On-Demand licenses.

All-or-None Support and Maintenance. Where Licensee purchases support and/or maintenance for the Licensed Software, Licensee hereby agrees that it shall purchase such support and/or maintenance services for all of Licensee's licensed units of such Licensed Software including all related development and deployment product licenses.

Updates and Upgrades. Upon delivery to Licensee of any Update and/or Upgrade, the license granted to such prior version and/or release being updated or upgraded shall terminate after a ninety (90) day transition period from such delivery and only the license to such Update or Upgrade shall continue unless (i) Licensee has paid to Licensor the applicable additional fees required by Licensor to use both versions, or (ii) in the case of an Update that is provided to Licensee at no additional charge from Licensor pursuant to support and/or maintenance for which Licensee has separately contracted, Licensee provides written notice to Licensor during the aforementioned transition period of its election not to use the Update but instead remain with the prior version and Licensee's de-installation and destruction of such Update.

Editions. Any reference to a Licensed Software product in this License Agreement shall also apply to such products various editions or variants except where otherwise specifically stated. For example, the terms and conditions applicable to Enterprise Developer also apply to Enterprise Developer for Eclipse, Enterprise Developer for Visual Studio, Enterprise Developer Connect, and Enterprise Developer for z, etc., and the terms and conditions applicable to Visual COBOL also apply to Visual COBOL for Visual Studio, Visual COBOL for Eclipse, Visual COBOL Development Hub, etc.

Bundles/Suites. If the Licensed Software is licensed as part of a bundle or suite of multiple products, and the applicable Product Order specifies the License Option and license count for the bundle or suite (but not the individual product components of the bundle or suite), then each product in the suite or bundle shall share such license type and count. Individual products in the bundle or suite cannot be used by multiple users if only one user license is purchased (for user-based licenses) and cannot be installed on multiple devices or servers if only one device or server license is purchased (for device or server-based licenses). For example, if Visual COBOL for XYZ is a bundle that includes Visual COBOL for XY and Visual COBOL for Z, and the applicable Product Order specifies that a single named user license for Visual COBOL for XYZ is purchased, then Visual COBOL for XY and Visual COBOL for Z would be limited to the same single machine for use by the same single named user. If COBOL Server for XYZ is a bundle that includes COBOL Server for XY and COBOL Server for Z, and the applicable Product Order specifies that a 4-Core license for COBOL Server for XYZ is purchased, then COBOL Server for XY and COBOL Server for Z would be limited to the same 4-Core machine.

Academic Editions/Users. Where Licensed Software is licensed under Licensor's Academic Program, in addition to the above terms and conditions:

  • (i) Licensee shall not use the Licensed Software for any purpose other than for non-commercial education or academic research activities.
  • (ii) Licensee shall not copy the Licensed Software, nor shall Licensee distribute, transfer or assign the Licensed Software without specific permission from Licensor.
  • (iii) License management: If Licensee is the academic institution using the Licensed Software for teaching purposes, Licensee will manage all student licenses through a license server provided by Licensor in accordance with guidelines provided by Licensor. Licensee agrees to provide reports describing the number of licenses Licensee has issued in each period upon Licensor's request.

Personal Edition Products.

  • (i) Licensee shall not use the Licensed Software for any purpose other than for personal educational and non-commercial activities. The Licensed Software may not be used for training or teaching purposes.
  • (ii) Licensee shall not: (a) use the Licensed Software to compile source code for applications of more than two thousand, two hundred (2200) lines of procedural code (exclusive of lines containing comments and/or blanks) in any one (1) application or (b) deploy or transfer such application on or to any other machine or third party; or (b) with respect to Enterprise Developer, use the Licensed Software for any purpose other than to input, edit and syntax check code for personal educational use.
  • (iii) Licensee shall not copy the Licensed Software, nor shall Licensee distribute, transfer or assign the Licensed Software without specific permission from Licensor.

Batch-Only Licenses. Where any Licensed Software is designated as "Batch-Only" using such description or similar terminology, such Licensed Software may only be used to perform batch processing.

PRE-EXISTING LICENSES. FROM COMMENCEMENT OF THIS LICENSE AGREEMENT, IF THE LICENSED SOFTWARE SUBJECT TO THIS LICENSE AGREEMENT IS THE MOST CURRENT VERSION OF THE LICENSED SOFTWARE LICENSED BY LICENSEE, THE "LICENSED SOFTWARE" SHALL ALSO INCLUDE, AND THIS LICENSE AGREEMENT SHALL APPLY TO, ANY PRE-EXISTING AND FUTURE LICENSES FOR ANY EARLIER VERSION OF THE LICENSED SOFTWARE LICENSED BY LICENSEE AND REPLACE ANY PRIOR END USER LICENSE AGREEMENTS APPLICABLE THERETO ("PRIOR EULA(S)"). NOTWITHSTANDING THE FOREGOING, IF THE EARLIER VERSION INCLUDES DIFFERENT COMPONENTS, ANY TERMS SPECIFICALLY APPLICABLE TO THOSE COMPONENTS IN THE APPLICABLE PRIOR EULA SHALL CONTINUE TO APPLY TO SUCH COMPONENTS. "ANY VERSION OF THE LICENSED SOFTWARE" SHALL ALSO INCLUDE THE RELATED DEVELOPMENT AND DEPLOYMENT/RUNTIME PRODUCTS OF SUCH LICENSED SOFTWARE.

ENDS


Contacting Micro Focus

Our Web site gives up-to-date details of contact numbers and addresses.


Further Information and Product Support

Additional technical information or advice is available from several sources.

The product support pages contain a considerable amount of additional information, such as:

  • Product Updates on Software Licenses and Downloads, where you can download fixes and documentation updates.
    1. Log into the Software Licenses and Downloads (SLD) site at https://sld.microfocus.com/mysoftware/download/downloadCenter .
    2. Select your account and click Entitlements.
    3. Search for the product by using any of the available search parameters.
    4. Click Show all entitlements.
    5. Click Get Software in the Action column for the product you want to download or update.

      In the File Type column, you see entries for "Software" for any GA products, and "Patch" for any patch updates.

    6. Click Download on the relevant row.
  • The Examples and Utilities section of the Micro Focus SupportLine Web site, including demos and additional product documentation. Go to https://supportline.microfocus.com/examplesandutilities/index.aspx.
  • The Support Resources section of the Micro Focus SupportLine Web site, that includes troubleshooting guides and information about how to raise an incident. Go to https://supportline.microfocus.com/supportresources.aspx

To connect, enter https://www.microfocus.com/en-us/home/ in your browser to go to the Micro Focus home page, then click Support & Services > Support. Type or select the product you require from the product selection dropdown, and then click Support Login.

Note: Some information may be available only to customers who have maintenance agreements.

If you obtained this product directly from Micro Focus, contact us as described on the Micro Focus Web site, https://www.microfocus.com/support-and-services/contact-support/. If you obtained the product from another source, such as an authorized distributor, contact them for help first. If they are unable to help, contact us.

Also, visit:

  • The Micro Focus Community Web site, where you can browse the Knowledge Base, read articles and blogs, find demonstration programs and examples, and discuss this product with other users and Micro Focus specialists.
  • The Micro Focus YouTube channel for videos related to your product..
Related information
Micro Focus SupportLine
Examples and Utilities
Support Resources
Micro Focus Community
White Papers and Webinars
Micro Focus YouTube Channel


Information We Need

If your purpose in contacting Micro Focus is to raise a support issue with SupportLine, you should collect some basic information before you contact us, and be ready to share it when you do.


Contact information

Our Web site gives up-to-date details of contact numbers and addresses.

Additional technical information or advice is available from several sources.

To connect to the product support pages, enter https://www.microfocus.com/en-us/home/ in your browser to go to the Micro Focus home page, then click Support & Services > Support. Type or select the product you require from the product selection dropdown, and then click Support Login.

If you are a Micro Focus SupportLine customer, please see the Welcome to Customer Care document that includes information about downloading and licensing your product, contacting Customer Care, and about reporting an incident. You can download it from our Web site. Support from Micro Focus may be available only to customers who have maintenance agreements.

You can download fixes and documentation updates:

  1. Log into the Software Licenses and Downloads (SLD) site at https://sld.microfocus.com/mysoftware/download/downloadCenter .
  2. Select your account and click Entitlements.
  3. Search for the product by using any of the available search parameters.
  4. Click Show all entitlements.
  5. Click Get Software in the Action column for the product you want to download or update.

    In the File Type column, you see entries for "Software" for any GA products, and "Patch" for any patch updates.

  6. Click Download on the relevant row.
Related information
Micro Focus Web Site
Micro Focus SupportLine
Welcome to Customer Care


The Micro Focus Community

In addition to this product documentation, visit the Micro Focus Community Web site to browse the Knowledge Base, read articles and blogs, as well as discuss this product with other users and Micro Focus specialists.


Help on Help

The latest up-to-date Help is available on the Micro Focus SupportLine Web site. Alternatively, you can display the Help locally from the Help menu in the IDE.

COBOL Help within the IDE

Tips on getting Help on COBOL when using the IDE:

  • COBOL syntax, library routines and Compiler directives. In the COBOL editor, put the cursor anywhere within the reserved word, routine or directive, and then press F1.
  • Error messages. In the output pane, put the cursor on the error message number and press F1.
  • Tooltips. Hover over an item in the COBOL code or over a field or control, by leaving the mouse pointer on it for a moment. A brief description of it may be displayed, either beside it or at the bottom of the window.
Note: Context help in the IDE that is provided as context help files, .HLP, might not work on versions of Windows such as Vista or later. This is because .HLP files require the Windows Help Program (WinHlp32.exe) which is not available in these versions of Windows. You need to install the Windows Help Program separately - click here to download the program.

Release Notes

The Release Notes accompany major releases and updates. They are available from the Product Updates section on the Micro Focus SupportLine Web site and your EPD email. On Windows, a link to the release notes is available from the startup screen during installation.

The Release Notes include information about new features for the release, system requirements and installation instructions, known technical issues, information about the issues that are resolved in the current release, and any changes in behavior that could potentially affect existing applications.

Readmes

This documentation includes two types of readmes:

  • Patch Update readmes contain information about issues that are resolved in a Patch Update, changes in behavior that could potentially affect existing applications, and any specific Patch Update installation procedures.
  • Samples' readmes contain information about how to install and execute a sample.

Unless otherwise stated, references to a "readme" will refer to a Patch Update readme.


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 5.0


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 (Versions 2013,2015 and 2017) 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:

    • 64-bit systems:

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

    • 32-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

    • Be aware that newer versions of SQL server might not be compatible with earlier versions of windows.

    • You will need SQL server management studio running on a machine somewhere (either the local machine or on the network) to be able to manage SQL server.

    • Make sure that the tcpip protocol is enabled in the SQL configuration manager.
  • If you are developing applications:
    1. Microsoft Visual Studio 2013 or later
    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 NET.TCP port sharing service.

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

  • WebSphere MQ

    The WebSphere MQ .NET Managed Code Client will need to be installed if your CICS or batch applications make use of the WebSphere MQ MQI verbs. Supported versions of the MQ .NET managed code client are:

    • WebSphere MQ 7.5.0.3 or later
    • WebSphere MQ 8.0 or later
  • To Activate Windows and IIS Components
  • To Install Additional Features on a Windows 2008 Server, or Windows 7
  • To Install Additional Features on a Windows Server (2012 or later), Windows 10 or Later
  • To Configure Process Logon Credentials
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.
    Note: Whilst the dialogs to install these features may change from release to release of Microsoft Windows, the core components are the same. The topics in the Setting up the Operating Environment section are provided as guides. Even if your OS version is slightly different, the principle is the same.
After you install Enterprise Server for .NET, run the wassetup command as administrator.
Parent topic: Setting Up the Operating Environment


To Install Additional Features on a Windows 2008 Server, or Windows 7

This topic refers to the Windows 2008 server version. When installing on Windows 7, the core requirements are basically the same. The selection dialogs might be different.

  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 6 Management Compatibility (select all available features)
    • Under Application Development, select:
      • .NET Extensibility
      • ASP .NET
    • Under Common Http Features, select:
      • Default Document
    • Under Security, select:
      • Request Filtering
  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.
  12. Check the WCF services are enabled and running:
    1. Open the services mmc via the control panel.
    2. Ensure that the Net.Pipe Listener adapter is enabled and started and set to autostart.
    3. Ensure that the Net.Tcp Listener adapter is enabled and started and set to autostart.
    4. Ensure that the Net.Tcp Port Sharing Service is enabled and started and set to autostart.
Parent topic: Setting Up the Operating Environment


To Install Additional Features on a Windows Server (2012 or later), Windows 10 or Later

To operate Enterprise Server for .NET on a Windows server (2012 or later), you need to install additional Windows features that are supplied with the installation software.

This topic refers to the Windows server 2012 version. Windows 10 might be slightly different, and later versions of Windows server might have a slightly different process, but the key components remain the same.

  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:
      • Default Document.
    • Under Security, select:
      • Request Filtering
    • 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. If framework 4.5 is installed, add the .NET Framework 4.5 features to include:
    • Named Pipe Activation
    • TCP Activation
    • TCP Port Sharing
  5. If framework 3.5.1 is installed, add the .NET Framework 3.5.1 Features:
    • WCF Activation
      • HTTP Activation
      • Non-HTTP Activation
  6. Apply and check the WCF services are enabled and running:
    1. Open the services mmc via the control panel.
    2. Ensure that the Net.Pipe Listener adapter is enabled and started and set to autostart.
    3. Ensure that the Net.Tcp Listener adapter is enabled and started and set to autostart.
    4. Ensure that the Net.Tcp Port Sharing Service is enabled and started and set to autostart.
Parent topic: Setting Up the Operating Environment


To Configure Process Logon Credentials

A working Server 2008 R2, or later, installation is required to perform these steps.
Some of the processes used by Enterprise Server for .NET need to be run as a Windows administrator user that has sysadmin permissions to access the SQL Server databases used by the system (i.e. region, cross-region and datastores). These processes are:
  • seemonitor.exe - the event monitor
  • w3wp.exe - the IIS application pools
  1. Configuring processes running on the same machine as the SQL Server instance

    By default, these processes are configured to run as the LocalSystem user. This user has Windows administrator privileges, but will not have any database access permission. To give LocalSystem database access, you must add the NT Authority\SYSTEM user as a user in the SQL server instance and give it sysadmin permissions.

  2. Configuring processes running on a different machine from the SQL Server instance
    1. Stop the seemonitor service if it is running.
    2. Modify the logon user for seemonitor.exe. Open the services management console (services.msc) and change the logon user for the seemonitor service to the required user and password.
    3. Modify the logon user for IIS. Open the IIS management console and navigate to the Micro Focus SEE for .NET (Dispatcher) v4.0 application pool. In the advanced settings, change the identity to the user you want to use. Do the same for the Micro Focus SEE for .NET (SEP) v4.0 application pool.
    4. In the SQL server instance, create the user(s) that you have just defined for the seemonitor.exe and w3wp.exe processes to run under, and give them sysadmin database access permission.
    5. Reset the IIS application pools using the wasreset /full command.
    6. Restart the seemonitor service.
Enterprise Server for .NET Administration UI

The Enterprise Server for .NET Administration UI also requires database access. This process should also be run as a Windows administrator user with sysadmin permissions to access the SQL Server database used by the system to ensure that all operations provided by the UI can be successfully performed. However, it is possible to run the UI as a Windows administrator user without sysadmin database permissions, but with a potential reduction in functionality. To do this, the user should be given the db_datareader access role in addition to being granted any of the permissions indicated in the following tables:

  1. Region database
    Permission Console View
    EXECUTE
    • Displaying

  2. Cross-region database
    Permission XA Resource Definitions Shared Catalog Definitions Security Configurations and Managers
    EXECUTE
    • Viewing
    • Adding
    • Adding
    • Viewing
    • Adding
    DELETE
    • Deleting
    • Deleting
    CONTROL
    • Deleting

  3. Datastore database
    Permission Datastore View
    EXECUTE
    • Reading file
    INSERT
    • Reading file
    • Downloading file
    DELETE
    • Closing file
    • Downloading file
    CONTROL
    • Uploading file
    CREATE DATABASE (master db)
    • Create datastore
    CREATE PROCEDURE
    • Reading file
    • Uploading file
    CREATE TABLE
    • Uploading file
Debugging

When debugging, the Visual Studio (devenv.exe) and seesep.exe processes also require database access. If the user running Visual Studio does not have sysadmin permission to access the region, cross-region and datastore databases that are to be used by the debugging sessions, then the user should be granted CONTROL permission to each. The user will also need to be granted VIEW SERVER STATE permission in the master database if datastore databases are used, as Enterprise Server for .NET's database file system support requires access to dynamic management views and functions (DMVs).

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 and run as Administrator.
  2. Enter the following command in the Administrator command prompt.
    wassetup
  3. ClickEnter.

    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. | 64 bit: %ProgramFiles%\Micro Focus\Enterprise Developer 32 bit: %ProgramFiles(x86)%\Micro Focus\Enterprise Developer
System configuration files. The read-only master resource definition and ESDEMO region startup files reside here. | 64 bit: %ProgramFiles%\Micro Focus\Enterprise Developer\etc\SEE\files\sys 32 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. | 64 bit: %ProgramFiles%\Micro Focus\Enterprise Developer \binAnyCPU\SEE 32 bit: %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\binAnyCPU\SEE
System WAS/IIS installation files. | 64 bit: %ProgramFiles%\Micro Focus\Enterprise Developer\binAnyCPU\SEE\WAS 32 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\5.0\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\5.0\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 > Configuration > Enterprise Server for .NET Admin .

    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\5.0\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 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, click Configuration Editors > Listener . See 1 in the diagram below. The Listener Configuration Editor view is displayed in the Results pane.
  2. Click 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 three child nodes: HTTP, 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. Click either File > Save, or the Save icon on the toolbar to save the file. See 7 in the diagram below.
  8. Click either Options > Start Listener, or the Start Listener icon on 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. Click Connection > Configure.

    The Connection Configuration dialog box appears.

  3. Select the TN3270 protocol. The TN3270 tab is now available.
  4. In 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. Set the target hostname, for example localhost. Click OK.
  5. Click Connection > Connect.

    The emulator connects to the region.

  6. 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:

    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\5.0\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. Click either File > Save, or the Save icon in the toolbar to save the file. See 7 in the diagram below.
  8. Click either Options > Start Listener, or 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 installed 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\5.0\SEE\config

The current software release contains the following:

  • Supplied Configuration Files - CICS
  • Sample: CICS ACCT Transaction
  • Sample - CICS BankDemo
  • Sample - BankDemo JES
  • 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\5.0\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\5.0\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 ESDEMO acct example.

This walkthrough covers 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 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 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. (Optional)This step 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 slash (/) when specifying the database name if required.

        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. You do not need 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
        • 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


Sample - BankDemo JES

The BankDemo JES sample builds upon the BANKDEMO CICS application and demonstrates a JCL job that extracts, sorts and prints a customer statement from the BankDemo database.

This sample uses resources stored on a local disk based file system rather than database-hosted.

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 JCLDEMO region and have successfully submitted a test JCL.

The BankDemo JES sample files are in%PUBLIC%\Documents\Micro Focus\Enterprise Developer\samples\Mainframe\JCL\DotNet\BankDemo.

Follow steps 1 and 2 of the CICS BankDemo sample to create the database and compile the application. Stop at the end of step 2, and do not deploy to the database.

Then complete the following steps:
  1. 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. Call the XA resource "bank" and associate it with the JESBANK region.
  2. Create the JESBANK 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 JES Region called JESBANK, hosted in the (local) database.
      2. Select the region startup called REGION_JESBANK.CONFIG file from the sample directory
      3. If you don't want to use the default catalog and data file locations, adjust them.
    2. Create a listener endpoint for the JESBANK region on a suitable mfbinp port.
    3. Start the region.
    4. Start the listener.
  3. Submit the JCL job entitled DEFBANK.JCL into the JESBANK region.
    1. This will create and initialize some required data sets in the catalog.
  4. Submit the JCL job entitled ZBNKSTMNT.JCL into the JESBANK region.
    1. This will perform three steps: extract, sort, and print.
    2. Examine the spool output at the end of the job to see the result.
Note:

The ZBNKSTMNT job runs three procs stored in the MF.PROCLIB PDS dataset:

  • YBNKEXTS - extracts the data from the database.

    It uses TSO syntax in a control card, KBNKTSO2.TXT stored in the MFI01.MFIDEMO.CTLCARDS PDS.

  • YBNKSRT1 - sorts the retrieved data.

    It uses sort parameters in a control card , KBNKSRT1.TXT stored in the MFIDEMO.MFI01.CTLCARDS PDS.

  • YBNKPRT1 - prints the statement.

    It invokes the COBOL program ZBNKPRT1 included in the BankDemo CICS sample.

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: None
  • 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: None
  • 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: None
  • 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: None
  • 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: None
  • 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: None
  • 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: None
  • 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: None
  • 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: None
  • 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 console log and Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions to help resolve 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 console log and Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions to help resolve 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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 console log and Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions to help resolve the problem
  • 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions to help resolve the problem
  • 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 successfully 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 successfully 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 successfully 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions to help resolve the problem
  • 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 log and Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions to help resolve the problem
  • 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 log and Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions to help resolve the problem
  • 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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 parameter 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 specified 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions to help resolve the problem
  • Module: seedeploy
DT0029I 1 file in datastore
Description: There 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions to help resolve the problem
  • 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions to help resolve the problem
  • 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the Applications and Services Logs > Micro Focus Server category of the Windows event log for exceptions 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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 with no exception occurred.
  • System action: none
  • User response: Use the abendcode and resp code to help isolate and rectify the problem
  • module: seesep
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: seesep
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: seesep
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: seesep
EP0007E An exception occurred: exception
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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 might 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows event log for further information to help resolve the problem
  • Module: seesep
EP0068E Failed to load JES engine 'JES engine assembly name'
Description: An exception occurred.
  • System action: The JES engine is unavailable for processing.
  • User response: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows event log for further information to help resolve the problem
  • Module: seesep
EP0069E An exception occurred processing JCL submission request: message
Description: An exception occurred.
  • System action: Operation terminates
  • User response: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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 alternative 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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 documentation 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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 anticipation 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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. Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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 shutting 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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: Check the console log and Applications and Services Logs > Micro Focus Server category of the Windows 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 anEnterprise Server for .NET Installation
  • Configuring the Operating Environment
  • Defining Program and Data Locations
  • Configuring Regions and Resources
  • About CICS Printers
    Enterprise Server for .NET has partial support for CICS printer devices connected using TN3270 clients.
  • Starting and Stopping a Region
  • Securing the Environment
  • Configuring XA resources
  • SEP Recycling
  • Administering from the Command Line
  • Historical Statistics Facility (HSF)
  • WebSphere MQ
  • System Monitoring and Recovery
  • Diagnostics
  • Enterprise Server for .NET Context Sensitive Topics
Parent topic: Administrator Role


Administering anEnterprise 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
  • Responding to Pending Console Input Requests
  • 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 anEnterprise 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. 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 anEnterprise 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 displays 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


Responding to Pending Console Input Requests

Batch and CICS applications can use ACCEPT FROM CONSOLE and EXEC CICS WRITE OPERATOR REPLY respectively to request input from the system console. When they do so, execution of the application is suspended until a reply has been received. When a request is made for console input by an application running under Enterprise Server for .NET, the request can be satisfied by replying using either of the following:
  • Enterprise Server for .NET Administration UI's Console View
  • seesys command-line utility
  • To Respond to a Pending Console Input Request from the Console View
Parent topic: Administering anEnterprise Server for .NET Installation
Related reference
seesys: administer a running system


To Respond to a Pending Console Input Request from the Console View

When an application requests console input, theEnterprise Server for .NET Administration UI's Console View can be used to issue the reply for the request.
  1. The UI will indicate that one or more console input requests are pending for a region, by overlaying the region icon in the Tree pane with a Message Pending icon. This is a useful indicator if the Console View is not currently being displayed. See 1 in the diagram below.

  2. Select the Console View. The console messages will include an SEEEP0177I message, indicating that an application has requested console input (see 2 in the diagram below), and an input area is displayed indicating the pending console input requests (see 3 in the diagram below).

  3. Click the Reply field associated with the console input request, type in your reply and click Enter. See 4 in the diagram below.

    The reply will be sent back to the application and the input area will disappear if there are no other pending console input requests. The Message Pending icon overlaying the region icon in the Tree pane will also be removed.

By default, the input area will only be displayed when one or more console input requests are pending, and then removed when the last request has been replied to. However, if you want the input area to always be visible in the Console View, you can drag the splitter at the bottom of the view to the position where you want the input area to start. If you want to revert to the default auto-show/ hide behavior, just drag the splitter back to the bottom of the view.
Parent topic: Responding to Pending Console Input Requests


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 anEnterprise 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 anEnterprise 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 anEnterprise 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

An Enterprise 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 anEnterprise 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 anEnterprise 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 > Configuration > Enterprise Server for .NET Admin 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\5.0\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

The system uses the Windows Communication Framework (WCF) for inter process communications.

The default settings used by the system should be adequate for most work, but in some cases tweaking these parameters using the application configuration files can be beneficial.

An example of when this should be done is in a very busy system with high load where the administration tool is viewing CICS trace data. The sheer volume of data might be too much for the default WCF buffer sizes. Changing maxReceivedMessageSize and MaxArrayLength in the monitor process would be appropriate.

For a WAS (IIS hosted) deployment, the SEP and Dispatcher parameters are in the appropriate web.config file.

The Listener and Monitor roles' default configuration files are 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
    • 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
    • The maximum number of messages actively processing across a role.
    • Default value is 512
  • Throttling.maxConcurrentSessions
    • 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 of all by 10. The example might 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>
Attention: 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.
CAUTION:
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
Related reference
seedeploy: deploy configuration files and programs to a database or Azure Drive


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
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, to define the locations that your applications use.
  • You can also define names and locations in a properties file, which you can specify 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.

When an environment variable and a pseudo-variable of the same name define different paths:

  • For deployment locations, such as path locations of configuration files deployed to a database,

    the pseudo-variable takes precedence over the environment variable. 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 run-time locations, such as path locations of maps and programs,

    the environment variable takes precedence over the pseudo-variable. 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
Related concepts
About Region Properties


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 Region Properties
  • About Entry Point Name Mapping
  • About File Handler Configuration
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\5.0\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\5.0\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) connects to the main database in the local machine using named pipe.
      • localhost connects to the main database in the local machine using TCPIP.
      • localhost\sqlexpress connects to the sqlexpress database instance on the local machine using TCPIP.
      • machineName\MSSQLSERVER connects 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.

    Enter the default service host name where the region will be run, for example localhost.

    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\5.0\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\5.0\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 Region Properties

Many applications make use of environment variables to configure their behavior. This is generally acceptable if the application is running on a single machine and isolated in its execution from other applications. However, when running applications under Enterprise Server for .NET, their execution may be distributed across several machines, or run alongside other applications in the same process. This poses the following problems:
  • When run across several machines, each machine must be configured to have exactly the same environment variables
  • When run in the same process, different applications may require the same environment variable to be set to different values to ensure the required behavior

To resolve these problems, Enterprise Server for .NET allows properties (name/value pairs) to be specified for each region in the system. The properties are specified when a region is cold-started and held in the region database. This ensures that any application running within a region, irrespective of which machine or process that is running it, will have a consistent set of properties available for it to use. The public MicroFocus.SEE.SEP.Public.SEPInfo.GetPropertyValue() method is provided to allow applications to retrieve property values at run-time.

Properties may be specified for a region to use by:
  • Creating a region properties file and specifying its use for the cold-start of a region
  • Specifying properties within a region start-up file

If properties are specified in both a region properties file and a region start-up file, the ones in the region properties file having the same names as ones in the region start-up file will take precedence. A separate region properties file would generally only be used if more than one region required exactly the same set of properties. Recommended use would be for each region start-up file to include all the properties that applications running under it will require.

In addition to properties that are required by a region's applications, properties may also be defined for folder/path parts of program and data locations specified in the region start-up file. The following example shows how a property named MYDIR could be used to define the high-level part of a program location:
        ...
        <programs>
          <location path="${MYDIR}/bin/debug" />
          <location path="${MYDIR}/tests/progload/bin/debug" />
          <location path="${MYDIR}/tests/progload/bin2/debug" />
        </programs>
        ...
  • To Create or Edit a Region Startup Properties File
  • To Start a Region With a Properties File (MMC UI)
  • To Start a Region With a Properties File (seestart)
  • To Define Properties in a Region Startup File
Parent topic: Configuring Regions and Resources


To Create or Edit a Region Startup Properties File

The Enterprise Server for .NET Administration UI is used to create and edit region startup properties files. A region startup property file can optionally be specified during region startup to define properties (name/value pairs) to be used by the region's applications at run-time. The properties are persisted in the region database during a cold-start. To create or edit a region startup properties file:
  1. In the Tree pane under Configuration Editors, click Region Startup Properties. See 1 in the diagram below. The Property File Configuration Editor will be displayed.
  2. Click on either the Create new file or Open file icon to create a new properties file, or edit an existing one respectively. See 2 in the diagram below.

    A grid will be displayed in which existing name/value pairs are displayed, and where new ones can be defined.

  3. Enter your name/value pairs in the grid. See 3 in the diagram below.
  4. Choose File > Save, or click the Save icon in the toolbar to save the file. See 4 in the diagram below

Parent topic: About Region Properties


To Start a Region With a Properties File (MMC UI)

For a region to be started with a properties file, the properties file must be associated with the region definition in the Enterprise Server for .NET Administration UI. To do this:
  1. In the Tree pane, under SEE Administration > Regions select the region to be configured and select the Properties view. See 1 in the diagram below.
  2. In the Results pane, select the Properties file location item, and use the browse button to locate and select the properties file to be associated with the region. See 2 in the diagram below.

You must cold-start the region for the changes to take effect
Parent topic: About Region Properties


To Start a Region With a Properties File (seestart)

For a region to be started with a properties file using the seestart command-line utility, the name of the properties file must be specified using the -properties option. For example:
seestart -region:JCLDEMO -properties:C:\Regions\jcldemo_properties.config
Parent topic: About Region Properties


To Define Properties in a Region Startup File

The properties to be used by a region are defined in the region start-up file. To do this:
  1. Open the startup file of the region you are configuring, with the Region Startup File editor. See To Edit a CICS Region Configuration or To Edit a Region Startup File Associated with a JES Region
  2. In the Results pane, expand the Region node and select the Properties node. See 1 in the diagram below.

    A grid will be displayed in which existing name/value pairs are displayed, and where new ones can be defined.

  3. Enter your name/value pairs in the grid. 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: About Region Properties


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


About File Handler Configuration

Instead of the COBOL file handler picking up its configuration from a fixed location for all regions on any given machine, Enterprise Server for .NET allows COBOL file handler configuration to be defined on a per-region basis via the region start-up file. The benefits for doing this are:
  1. If Enterprise Server for .NET is scaled out across multiple machines, it eliminates the possibility of the COBOL file handler being configured differently on each machine if the same extfh.cfg file is not used. This ensures consistent application behavior from machine to machine.
  2. It is very likely that different Enterprise Server for .NET regions will require different COBOL file handler configuration according to the applications that are being run.
  • To Define File Handler Configuration
Parent topic: Configuring Regions and Resources


To Define File Handler Configuration

This procedure demonstrates how to define File Handler Configuration for a CICS or JES region 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. 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 File Handler node. See 1 in the diagram below.
  3. Enter the file handler configuration statements in the Configuration statements edit box. See 2 in the diagram below.
    Note: The format of the configuration statements is exactly the same as that which you would use in a standalone extfh.cfg file.
  4. Click File > Save, or click the Save icon on 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: About File Handler Configuration


About CICS Printers

Mainframe CICS supports two main kinds of printing over TN3270 connections: SNA Character Stream (also called SCS or LU1) and 3270 datastream (also called 3270DS or LU3). SCS is similar to many PC printer languages; it combines output text with control sequences. 3270DS uses the same 3270 output operations as a 3270 terminal, so printer output is formatted as a series of pages that correspond to screens of terminal output. (Of course input fields in the 3270 output have no effect for 3270DS print operations.) Enterprise Server for .NET supports both types of printer devices.

Mainframe CICS lets printer devices connect to the region in the same way that terminals do. If the printer client doesn't request a particular terminal name, it will be assigned one that corresponds to a suitable terminal model and terminal type. The printer client can also request a specific "device name" or "LU name". If there is a terminal definition installed in the region with a netname that matches the requested name, and that terminal isn't already attached, and it refers to a printer-type device, then the printer will be given that terminal ID. Usually printers are connected to a specific terminal ID this way so print output can be sent to them, for example by doing an EXEC CICS START specifying the printer's terminal ID as the facility, to start a task that writes to the printer with EXEC CICS SEND.

Mainframe CICS also lets a printer device connect with a request to "associate" itself with an existing terminal session, so that print output from transactions started by that terminal will automatically go to the associated printer. Enterprise Server for .NET does not currently support the printer-association feature.

TN3270 printer clients usually can send their output to any printing output destination available on the system where they're running, including virtual printers such as "print to file" destinations. See the documentation for your TN3270 software for more information.

Selecting the printer type

In Enterprise Server for .NET, each connected printer client only handles one type of output, either SCS or 3270DS. Applications that generate print output are almost always written to support only one of the two data streams, so you will need to configure your CICS printers to use the data stream your applications require. (If you have a mix of SCS and 3270DS applications, you can configure two or more printer clients. Multiple printer clients can print to the same physical printer.)

The "classic" TN3270 protocol only supports 3270DS printers. Clients connecting using this protocol will always be 3270DS.

Most TN3270 client software supports the newer TN3270E protocol, which includes SCS support. During TN3270E negotiation, clients can tell the region whether they support SCS, 3270DS, or both. If a client only supports one datastream, it will connect as that type of printer.

If a client announces that it supports both SCS and 3270DS, Enterprise Server for .NET determines what kind of printer it will be:

  1. If the printer does not ask to connect as a specific terminal (by sending a "device name" or "LU name"), it will be a 3270DS printer by default.
  2. If the device name sent by the printer matches a CICS terminal definition's netname attribute, and that terminal definition specifies a CICS TypeTerm (terminal type) resource, and the TypeTerm has a device type attribute of "SCSPRINT", "3790", or "3270P1", then the printer will be an SCS printer. (All three attribute values have the same meaning. They are defined as synonyms for compatibility with mainframe CICS and native Enterprise Server.)
  3. Otherwise, the printer will be a 3270DS printer.

So to use SCS printing, you need a TN3270 client that supports the TN3270E protocol and SCS printing, and you need to define a TypeTerm and Terminal in the resources for the CICS region.

  • To Configure an SCS Printer
    Configure an SNA Character Stream printer for Enterprise Server for .NET CICS applications.
Parent topic: General Administration


To Configure an SCS Printer

You should be familiar with the Enterprise Server for .NET management console and the process of creating CICS resource definitions.
Enterprise Server for .NET CICS supports two types of printers: SCS and 3270DS. By default, printer devices use the 3270DS data stream. If your CICS applications require SCS, you will need to configure an SCS printer for them. See About CICS Printers.
  1. Open your CICS resource definition file in the resource definition file editor.
  2. Open the CICS resource group for your new definitions. If you do not have a suitable group, create one. (You cannot change the system-supplied groups, which have names starting with "DFH".)
  3. Add a new TypeTerm resource. You can use any resource name not already used for a TypeTerm, such as "SCSPRT".
  4. Set the Device field of the TypeTerm to "SCSPRINT". The other attributes can generally be left with their default values.
  5. Add a new Terminal resource, or edit the Terminal resource for this printer if you have already defined it. The resource name should be the CICS facility name (terminal ID) that your applications expect to use for printing. (This may be a facility name specified in an EXEC CICS START command, or the facility name associated with a TD queue that uses a trigger transaction to send data to the printer, for example.)
  6. Set the Net Name attribute of the Terminal to a device name not already used by any of your Terminal definitions, and not starting with "NET". Make a note of the name you choose.
  7. Set the TypeTerm attribute of the Terminal to the name of the TypeTerm you created in step 3. The other attributes can generally be left with their default values.
  8. Save your resource file. Restart your CICS region or install the group that contains your new definitions.
  9. Configure your TN3270 client software to connect a printer using the Net Name you choose in step 6 as its "device name" or "LU name". Make sure it is configured to use the TN3270E protocol (this is often the default). If necessary, specify SCS printing; for many clients, both printer data streams are enabled by default.
Parent topic: About CICS Printers
Related information
About CICS Printers


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 an 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
  • External Security Feature
  • 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 logon 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 logon 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
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. 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.

Parent topic: Using Logon Providers


Configuring Logon Providers

You select a logon provider by adding an entry to machine.config. 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.

To specify a logon provider, set the Security.users.logonProvider option to the name of the logon provider assembly. The default logon provider supplied with Enterprise Server for .NET is MicroFocus.SEE.Logon.Windows. 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.

  • To Set Impersonation Options using machine.config
Parent topic: Using Logon Providers


External Security Feature

The External Security Feature (ESF) lets Enterprise Server for .NET rely on other facilities, such as the operating system and LDAP directories, to make security decisions.

These facilities, or External Security Managers, can participate in verifying user credentials, configuring user account properties (user group membership and attributes such as idle timeout), and making resource access decisions - whether a task is allowed a certain level of access to a specific resource, such as a file or program.

ESF includes a security manager which is built into Enterprise Server for .NET, various APIs, and pluggable modules known as ESM modules which are used to communicate with External Security Managers.

Enterprise Server for .NET includes some ESM modules, and others can be developed by Micro Focus, customers, or third parties such as Systems Integrators.

ESF is modeled on IBM's SAF (Secure Access Facility) for zOS, and to some extent on IBM's RACF (which is a SAF provider), but it does not try to provide exact mainframe compatibility. Some mainframe APIs are supported in a fashion similar to those available under zOS.

ESF in Enterprise Server for .NET is based on ESF for the native version of Enterprise Server, but because it is a completely separate implementation (due to the different requirements of Enterprise Server for .NET) it may not always behave identically.

This release supports only a subset of the native ESF features.

For example, note that it does not provide:

  • Support for changing user passwords (this will be implemented soon).
  • The ESF Admin API.
  • The Audit mechanism.
  • Tracing support is currently limited.

    This will be improved soon.

  • The ESF User Exit feature.
  • Support for passtokens.

    (These are mostly used in native ES to support single-sign-on between MFDS and ESMAC. There is no equivalent need in Enterprise Server for .NET.)

  • Nested groups.
  • CICS resource access control.
  • Result caching.

It does, however, provide:

  • Basic support for securing user signon using Windows user accounts and/ or user objects defined in Active Directory.
  • Resource access control for jobs running under JES.
  • User impersonation.

    Regions can be configured so that application code executes under the identity of the user running the job (for JES) or submitting the transaction (CICS).

  • Overview
  • Configuration
  • ESM Modules Included in ES for .NET
  • ESF-Administering ESF Configuration
  • Configuring JES Region To Use A Security Configuration
  • Configuring Windows Users - Impersonation - LDAP Resource Control
Parent topic: Securing the Environment


Overview

ESF is enabled on a per-region basis by associating the region with a security configuration. Regions which use the same cross-region database can share security configurations. The security configuration can specify one or more security managers (ESMs) to use. See ESF Configuration for more information about configuration.

At region startup, Enterprise Server for .NET configures ESF. If there is no security configuration (or if the configuration effectively disables security, for example by not specifying any ESMs to use), ESF is configured to simply return "allow" for all security requests.

During processing, the Enterprise Server for .NET engine makes various calls to ESF. (Application programs can also call ESF to make their own security checks, using various APIs.) If ESF is enabled, it will process the requests by calling each configured ESM module, which in turn contacts its ESM to resolve the request, as applicable. (Some ESMs do not handle certain types of requests.) In most cases, ESF calls ESM modules until one returns a definite response (allow or deny the request).

If none of the ESM modules can provide an answer for the request, ESF applies a default result of allow or deny based on its configuration.

The result is returned to the Enterprise Server for .NET engine, which will take the appropriate action.

Parent topic: External Security Feature


Configuration

The security configuration contains various options, such as whether to permit access to resources that have no applicable security rules, and a list of security manager names. These names correspond to security manager configurations, which are also stored in the cross-region database. Security manager configurations can be shared by security configurations.

When a security configuration lists more than one security manager, the security managers are invoked in the order specified. This is often important in determining how security requests are handled.

A security manager configuration specifies the ESM module to use, plus various parameters and options for interacting with the ESM and how the ESM module should behave. The precise meaning of the various settings varies among ESM modules.

Security configurations and security manager configurations also contain a "configuration text" area, which is free-format text. ESF and most ESM modules allow various additional options to be configured in this area using "ini-format" text:

[section-name]
 name=value
.....
[section-name
....

Additional details can be found later in this document.

For example, an administrator might create the following security manager configurations:

  • A configuration named "Windows Logon" using the LogonEsm ESM module, which verifies user credentials (username and password) with a standard Windows logon.
  • A configuration named "Production Resources" using the LdapEsm ESM module, which uses an LDAP repository such as Active Directory. In this example, this manager is configured to communicate with the domain AD server, where rules for access to production resources have been stored.
  • A configuration named "Development" using the LdapEsm ESM module. In this example, this manager is configured to communicate with an instance of Microsoft AD/LDS, which was configured with both user account information and resource access rules for developers.

Then, the administrator creates two security configurations:

  • The "Production" security configuration.
    • This specifies two security managers: Windows Logon and Production Resources. Here Windows Logon will handle user signon to the production region, because it's specified first. Since the LogonEsm ESM module does not process Auth requests, resource access will be governed by the Production Resources manager, using rules it extracts from Active Directory.
  • The "Development" security configuration.
    • This specifies just the Development security manager. Both user signon and resource access control will be handled by LDAP configuration in the AD/LDS repository.

The administrator configures the production and QA / UAT regions to use the Production security configuration, and developers create their own development regions using the Development configuration.

Creating and modifying ESF configurations

You can create and edit ESF security configurations and security manager configurations using the ESF Administration user interface. Enterprise Server for .NET also provides a command-line tool, seeseccfg.exe, for administering these definitions. It can create, delete, and list definitions in a cross-region database, and import/ export them from/ to XML, which can be edited manually, backed up, committed to a change-management system, etc.

To associate a security configuration with a region, you can use the ESF Administration user interface. You can also edit the region definition file (an XML document) directly.

In the Enterprise Server for .NET Administration tool, expand the System section of the SEE Administration tree to find the "Security Configurations and Managers" area, to create or modify security definitions. To associate a security configuration with a region, use the region definition editor as you would for other region properties.

Running the seeseccfg tool with no parameters will display a usage message.

Security Configuration properties

These are the properties that can be defined for a security configuration:

  • Name

    Required. The name of the security configuration.

  • Cache limit and Cache time-to-live

    Currently these have no effect. When ESF caching is implemented, the limit will be an optional integer specifying the approximate cache size in KB (0 or empty disables caching), and time-to-live will be an integer specifying the time in seconds before a cache entry expires.

  • Allow unknown resources

    Determines the result of a resource access query when none of the configured managers can answer it. If this option is enabled, access is allowed; otherwise access is denied.

  • Allow unknown users

    Determines the result of a user signon when none of the configured managers can answer it. If this option is enabled, the user is signed on; otherwise the user is rejected.

  • Create audit events

    Currently this has no effect.

  • Use all groups

    If enabled, permissions for each task are based on the signed-on user and all the groups that user belongs to; otherwise, only the permissions of that user and the sign-on group apply. (If no sign-on group was specified when the user signed on, the user's default group is used.) See the native ES documentation for more information.

  • Verify against all

    If this option is enabled, a user is signed on only if all the security managers associated with this configuration permit it. If the option is not enabled, the user sign-on process (Verify request) stops when one manager allows the sign-on.

  • Security Managers

    Lists the managers which will be invoked, in order, to process each security request.

  • Configuration

    An area for free-format configuration text. By convention, this is ini-format text, as described above. In this release no settings are defined for this area.

Security Manager properties

The properties that can be defined for a security manager:

  • Name

    Required. The name of this security manager.

  • Description

    Optional description text for the manager.

  • ESM module name

    Required. The name of the ESM module. This can be a complete pathname or just the name of the module with or without the .dll extension (for example "LdapEsm"). If a path is not specified, the module will be loaded from binAnyCpu\SEE\System in the product installation directory. See the next section for modules supplied with this release.

  • Cache limit and Cache time-to-live

    Currently these have no effect. See the description under Security Configuration properties above.

  • Disable security manager

    If checked, this security manager will not be used. It can be included in a security configuration but will not be loaded or invoked.

  • Connection path

    Instructs the ESM module how to connect to its ESM. The format depends on the modules. Of the modules included in this release, only the LdapEsm uses this property. See the section on configuring LdapEsm below.

  • Authorized ID and Password

    Some ESM modules use these properties to authenticate themselves to their ESMs. Currently only the LdapEsm uses these properties. See the section on configuring LdapEsm below.

  • Configuration

    An area for free-format configuration text. By convention, this is ini-format text, as described above. The interpretation of this text depends on the ESM module. See the sections below on configuring individual modules.

These properties can be configured using the Enterprise Server for .NET administration console or the seeseccfg utility.
Parent topic: External Security Feature


ESM Modules Included in ES for .NET

In this release, Enterprise Server for .NET ships with three ESM modules:

  • LogonEsm
    • This module handles user verification only. It uses the Enterprise Server for .NET Event Monitor service and its configured Logon Provider, which by default verifies users using the Windows LogonUser API. LogonEsm is similar to the OS ESM Module for native ES. If the Logon Provider returns a Windows security token, the Event Monitor makes that token available to the SEPs for user impersonation. User impersonation must also be enabled in machine.config to take effect. For more information see these topics in the product documentation:
  • LdapEsm
    • The LdapEsm module communicates with an LDAP server such as Active Directory. It can perform user verification, resource access control, or both. (A security configuration can include multiple security managers that use LdapEsm, if it's necessary to use multiple LDAP directories.) LdapEsm is the equivalent to the MLDAP ESM Module in native ES, though it does not currently provide all the same features.
    • For user verification, LdapEsm supports both verifying passwords against salted password hashes stored in Micro Focus format, and verifying user credentials by binding to the LDAP server.
    • LdapEsm uses the same LDAP object classes as the MLDAP ESM, and with it the same security definitions can be used by native ES and ES for .NET. For more information see these topics in the product documentation:
  • NullEsm
    • This is an ESM module provided primarily for testing purposes. By default it does nothing. It can be configured to recognize specific user-verification and resource-access requests and return a specified result for them.

A security manager uses one of these modules. A security configuration with multiple managers (also known as "stacking" security managers) can use managers that specify the same or different modules.

  • Using The ESM Modules
Parent topic: External Security Feature


Using The ESM Modules

This topic covers the specifics of using the ESM modules included in this release of Enterprise Server for .NET.

For background, Micro Focus recommends users be familiar with ESF in native ES, or review the documentation for native ES security:

Be aware that the ESM modules provided with Enterprise Server for .NET are somewhat different from those included with native ES.

  • LogonEsm
  • NullEsm
  • LdapEsm
Parent topic: ESM Modules Included in ES for .NET
Related reference
MLDAP ESM Module


LogonEsm

LogonEsm

The LogonEsm ESM module verifies user credentials by contacting the Event Monitor service and asking it to invoke the configured Logon Provider. The default Logon Provider does a Windows LogonUser, usually against the domain. See the product documentation for more information about Logon Providers:

LogonEsm is also capable of obtaining Windows security tokens, which are distributed to SEP instances by the Event Monitors. This is required for the Enterprise Server for .NET user impersonation feature.

The LogonEsm ESM module has no required configuration. None of the optional configuration settings affect its behavior.

LogonEsm is an ESF interface to the Logon Provider mechanism which was added to Enterprise Server for .NET before ESF was available. Consequently, it has some optional configuration settings in machine.config. Some of these are processed by LogonEsm itself; others are used by the Event Monitor service or the Logon Provider. See the descriptions of these settings in the product documentation.

Parent topic: Using The ESM Modules


NullEsm

Configuring NullEsm

The NullEsm ESM module has no actual External Security Manager. It makes security decisions internally, based on its configuration. By default it does nothing. It is intended primarily for testing, though it may be useful to configure a handful of exceptions for special purposes.

The NullEsm ESM module supports some optional settings in its configuration text area:

  • [Operation]
    • Regex=setting

      If setting is "y" or "yes" (case-insensitive), settings in the [Auth] section are treated as regular expressions rather than literal names.

  • [Trace]
    • Trace=setting

      If setting is "y" or "yes" (case-insensitive), write various messages to the console log about security decisions.

  • [Verify]
    • user =action

      For a Verify (user sign-on) request, if the userid matches user, then set the result based on action.

      The action can be:

      • allow Allow this signon attempt.
      • deny Deny this signon attempt.
      • disable Return a result code indicating the user's account is disabled.
      • expire Same result as disable.
      • fail Return an error indicating the ESM failed to process the request.
      • unknown Indicate the ESM does not have any information about this user.

      If the userid is not found in the [Verify] section, or the action is not recognized, the behavior is the same as for unknown.

    • [Auth]
    • class /resource=action

      When an Auth (resource access check) request is received, NullEsm concatenates the resource class and entity names with a slash separator and looks for a matching entry in the [Auth] section. If the Regex setting (see above) is enabled, it treats the entries as regular expressions rather than looking for a literal match. If it finds a matching entry, it sets the result based on action:

      • allow

        Allow this access attempt.

      • deny

        Deny this access attempt.

      • trace

        Log a message to the console about this access attempt. (The Regex mode is particularly useful if trace is used, as it makes it possible to have both an allow/deny entry and a trace entry for a given resource.)

Parent topic: Using The ESM Modules


LdapEsm

Configuring LdapEsm

The LdapEsm ESM Module uses an LDAP server as its External Security Manager. The LDAP server is primarily used as a repository of security configuration information, including user accounts, user groups, and resource access control rules. It can also be used to validate user credentials; see the discussion of "bind mode" below.

The LdapEsm ESM Module has more configuration options than most, since it must interact with an LDAP server, deal with an arbitrary LDAP directory structure, and support a number of processing options. In general, the LdapEsm tries to use the same options as the native ES MLDAP ESM Module, for features it supports. See the documentation for the MLDAP ESM Module for more information:

Security configuration: Use all groups

LdapEsm is affected by the Use all groups option of the Security Configuration for the region which is using it. In Use-all-groups mode, when a user signs on, the module will search the LDAP directory for group objects that list the user, and add them to the supplemental group list in the ACEE (Access Control Environment Entry). When a resource access request is made, the module will search all of the groups in the ACEE when matching against Access Control List entries.

Security manager connection options

LdapEsm uses the connection options in the security manager configuration, if specified, to connect to the LDAP server:

  • Connection path

    Tells LdapEsm where to find the LDAP server. This can be:

    • Empty, in which case the module uses "127.0.0.1:389".
    • A hostname or IP address (uses the standard LDAP port, 389).
    • A URL of the form "ldap://host:port" or "ldaps://host:port". The "ldaps" scheme specifies LDAP-over-TLS (secure connection). The ":port" is optional and defaults to 389 for plain LDAP and 636 for secure LDAP.
  • Authorized ID and Password

    Optional username and password to connect to the LDAP server.

    If not specified, the module uses the same default username and password as the native MLDAP ESM Module.

    • The username may be a plain username, a Distinguished Name, or some other format supported by the LDAP server.

Processing options for LdapEsm are set in various sections of the configuration text area.

Configuration text

Processing options for LdapEsm are set in various sections of the configuration text area.

[LDAP]
Base=dn
User container=dn
Group container=dn
Resource container=dn
User class=class-name
Group class=class-name
Resource class=class-name
User ID attribute=attribute-name
Search scope=scope
Referrals=referrals

The [LDAP] section specifies aspects of the LDAP repository and how the module should instruct the server to act. Many of these settings can be omitted and the defaults used.

The Base and container settings tell the module where in the LDAP hierarchy to find user and resource-rule objects. The values are LDAP distinguished names. If Base is not empty, it is appended to the three container settings. The default base is " CN=Micro Focus, CN=Program Data, DC=local ". The default containers for users, groups, and resources are " CN=Enterprise Server Users ", " CN=Enterprise Server User Groups ", and " CN=Enterprise Server Resources ". These correspond to the sample LDAP configuration supplied with the product.

The three class properties and the User ID attribute can be used to configure the module for LDAP schemas other than the one used in the default configuration. See the product documentation for more information.

The scope value determines whether just the immediate container or all containers within it are searched. The default is "one-level" (search only the immediate container); setting it to "subtree" searches all levels within the container recursively. There is a performance cost for subtree searches.

The referrals setting determines whether the LDAP server is allowed to pass requests it cannot answer on to other servers. By default this is disabled; setting this value to "yes" allows referrals.

[Verify]
mode=mf-hash | bind

The mode setting in the [Verify] section determines how user credentials are validated. In the mf-hash mode, which is also the default, LdapEsm searches for a user object in the user container with the userid as its common name (the first CN part of the object's distinguished name). If it finds one, it retrieves the value of the microfocus-MFDS-User-Pwd attribute, which is (normally) a salted cryptographic hash of the user's password. It hashes the supplied password with the same salt value and compares the hashes to determine if the password is correct.

In the bind mode, the module tests the supplied credentials by using them to bind to the LDAP server. The user is verified if the bind succeeds. The server determines how credentials are evaluated. Active Directory, for example, performs the equivalent of a Windows domain logon with them. Refer to the documentation for your server for more information.

[Trace]
Trace=setting
If setting is "y" or "yes" (case-insensitive), write various messages to the console log about security decisions. Currently LdapEsm just writes a message about each Auth request. (More extensive tracing will be provided in future releases.)
Parent topic: Using The ESM Modules


ESF-Administering ESF Configuration

To configure security configuration, open the Enterprise Server for .NET Administration UI.

Select the System > Security Configurations and Managers node in the system, as in 1 above. Right-click and add the server instance if one is not already defined.

Click OK.

Expand the Security and Configuration Managers node (1).

Select the server instance you want to configure (2).

Click Add (3).

Click the Security Manager Definition menu item (1).

Enter the appropriate fields as above.

  1. Name

    The name of this Security Manager Definition.

  2. Description

    A description of this Security Manager Definition.

  3. ESM Module Name

    The name of the External Security module that will be loaded.

  4. Cache Limit

    If the module has a configurable cache for holding responses from the security manager, enter its maximum size in kilobytes here.

  5. Cache Time to Live

    If the module has a configurable cache for holding responses from the security manager, enter the maximum time in seconds that an entry in the cache can be used to satisfy requests before the details must be re-queried from the security manager.

  6. Disable security manager.
  7. Check this box to disable this security manager.

For the Connection Details tab.

  1. Connection Path

    If the module requires a connection string that tells it how to connect to the external security manager, specify it here.

    The information supplied in the string and its format depend on the module that you are using. For details, please see the documentation supplied with the module.

  2. Authorized ID

    If the module requires an ID to connect to the external security manager, specify it here.

    As with the connection path, the content and format of these fields depend on the module that you are using. For details, see the documentation supplied with the module.

  3. Password

    If the module requires a password to connect to the external security manager, specify it here.

    As with the connection path, the content and format of these fields depend on the module that you are using. For details, see the documentation supplied with the module.

For the Configuration Tab

  1. This is a free-format text box where you can enter further configuration parameters that may be required for an ESM module.

Create a New Security Configuration Definition.

Click Add again, and select Security Configuration Definition.

  1. Name

    The name used to identify this Security Configuration.

  2. Cache Limit

    Enter the maximum size in kilobytes that the Directory Server or enterprise server's security facility can use for caching the results of security queries.

  3. Cache Time to Live

    Enter the maximum time in seconds that an entry in the cache can be used to satisfy requests before the details must be re-queried from the security manager.

  4. Allow unknown resources

    Check this if you want the security facility to permit access to any unknown resource; that is, any resource for which all entries on the priority list return Unknown.

    You might use this in circumstances where you only want to restrict access to some resources.

  5. Allow unknown users

    Check this if you want to allow unknown users to log in.

  6. Create audit events

    Check this to enable the enterprise server or Directory Server to generate security audit events. These events can be captured and logged by the Audit Facility.

  7. Use all groups

    Check this if a user requesting authorization is to have the permissions of every group to which he belongs.

    Uncheck this if the user is to have only the permissions of the group specified in the initial security API call that requested verification (authentication) of the user's credentials. Where no group is specified in the verify call, a default group is used.

  8. Verify against all

    Set this if you want each security query to be checked by all entries on the Security Manager Priority List.

    If this is not set, the entries will be queried in the order that they appear on the Priority List until one gives a response of Allow, Deny, or Fail (equivalent to Deny). This response will then be used to decide what action should be taken.

    If this field is set, all entries on the list will be queried, and if any returns a Deny or Fail, the access request will be denied. If there are no Deny or Fail responses and at least one of the entries on the list gives Allow as its response, the request will be allowed.

    If a security manager does not have a rule for the resource or user specified in the request, it gives a response of Unknown. Whatever the setting of the Verify against all Security Managers field, if all of the entries on the priority list respond with Unknown, the request will be denied unless you have checked Allow unknown resources or Allow unknown users.

For the Security Managers tab

  1. Select the Security manager required to participate in this configuration.

    Once added, the order in which the security manages are called is configured by moving them up and down using the appropriate buttons.

For the Configuration tab

  1. This is a free-format text box where you can enter further configuration parameters that may be required for this configuration.
Parent topic: External Security Feature


Configuring JES Region To Use A Security Configuration

To configure a region to use a security configuration, open the Enterprise Server for .NET Administration UI and edit the region configuration as follows:

  1. Click the ellipsis and select the security configuration from the drop down list.
  2. Save your region configuration.
  3. Restart the region.
Parent topic: External Security Feature


Configuring Windows Users - Impersonation - LDAP Resource Control

This topic describes an ESF configuration that might be used for a typical production JES region.

  • ES users are Windows users. They use their Windows usernames and passwords when submitting jobs or otherwise authenticating.
  • Application program code runs under the security token of the job user.
  • Resource access is controlled by security rules stored in Active Directory (or another LDAP server). These rules are grouped by resource class and applied based on the resource name, with wildcard matching. The rules contain Access Control Lists (ACLs) which specify permissions by user and group (again with wildcard matching). They use the same rule format as native ES, and can share rules with native ES.

To define this configuration:

  1. Set up an LDAP repository for ES security.
    1. If you already have an LDAP repository configured for security for native Enterprise Server, you can use that and proceed with step 2. Otherwise:
    2. Identify or install and configure an LDAP server. For ease of configuration, Micro Focus recommends Active Directory or an instance of Microsoft's AD/LDS (Active Directory Lightweight Directory Services).
    3. Configure the repository for ES security using the procedure for native Enterprise Server. Refer to the product documentation:
  2. Create a Security Manager that specifies the LogonEsm ESM module. In most cases, none of the other configuration settings for this manager need to be changed from their defaults.
  3. Create a Security Manager that specifies the LdapEsm ESM module. Configure it to use your LDAP repository from step 1:
    1. On the General tab, provide a name. Use "LdapEsm" as the module name. Make sure Disable security manager is not checked.
    2. On the Connection Settings tab, set the Connection path to the hostname and port of your server. (These can be omitted if using the defaults.) If you want a secure connection (LDAP-over-TLS) and the server is configured for it, specify these using the form ldaps://hostname[:port].
    3. Add settings under the Configuration tab as necessary, based on your repository structure. See the section on configuring the LdapEsm above for more information. If you are using the sample LDAP configuration supplied with the product with a new AD/LDS instance, you probably will not have to add any settings here.
  4. Create a Security Configuration that specifies your security managers from steps 2 and 3, in that order (LogonEsm manager first and LdapEsm manager second).
  5. Edit your JES region, configuring it to use the security configuration from step 4.
  6. Start the region. If there are any issues, review the previous steps and the security rules in the LDAP repository.
  7. Submit a job using the cassub command-line utility. Specify a valid username and password with the -u and -p options to cassub. As with the previous step, if there are any issues, review the previous steps and the security rules in the LDAP repository.
  8. Ensure the job you submitted runs properly (start an initiator for the job class if necessary).
  9. Once the region runs correctly with your security configuration, enable user impersonation:
    1. Stop all running regions and exit the Enterprise Server for .NET management console.
    2. Stop the Enterprise Server for .NET Event Monitor service using the Services control panel or the command net stop seemonitor.
    3. Follow the instructions in the product documentation for editing machine.config to enable user impersonation:
    4. Run the wasreset.cmd script (included with the product) to restart WAS-hosted processes.
  10. Repeat steps 5 - 8 to test execution with user impersonation enabled.

To investigate any problems encountered during this process, be sure to consult the Windows Security event log and the Micro Focus Server event log as well as the region console log.

Parent topic: External Security Feature


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 a Database XA Resource Definition
  • To Create an MQ XA Resource Definition
Parent topic: General Administration
Related tasks
To Create a Database XA Resource Definition
To Create an MQ XA Resource Definition
To Associate a Database XA Resource with a CICS Region Startup File
To Associate a Database XA Resource with a SIT
To Associate a Database XA Resource with a PCT
To Associate an MQ XA Resource with a CICS Region Startup File
To Associate an MQ XA Resource with a SIT
seexadef: administer XA resource definitions
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 (using DSNALI, DSNRLI or the TSO DSN command) uses a SQL database. A database 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.
  • a CICS region or batch application (using DSNRLI) uses WebSphere MQ. An MQ XA resource definition identifies the region it is associated with, the MQ queue manager name, and optionally the MQ channel and MQ connection name.
XA resource definitions are persisted in the cross-region database.

Database XA Resource Definitions

For CICS regions, a database 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 a 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, DSNRLI or when invoking the TSO DSN command. No additional configuration is required for JES regions. Enterprise Server for .NET.

MQ XA Resource Definitions

For CICS regions, an MQ XA resource definition can be associated with a region. A region association is made by naming the XA resource to be used as a 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.

For JES regions, the MQ channel and connection names used when an application attempts to explicitly connect to a queue manager, using the MQCONN or MQCONNX APIs, need to be specified in the region start-up file. Alternatively, if DSNRLI is being used, an XA resource definition is required for each queue manager that is to be connected to.

Parent topic: Configuring XA resources
Related tasks
To Create a Database XA Resource Definition
To Create an MQ XA Resource Definition
To Associate a Database XA Resource with a CICS Region Startup File
To Associate a Database XA Resource with a SIT
To Associate a Database XA Resource with a PCT
To Associate an MQ XA Resource with a CICS Region Startup File
To Associate an MQ XA Resource with a SIT
seexadef: administer XA resource definitions
Related information
Configuring XA resources
DSNALI Functionality
DSNRLI Functionality


To Create a Database XA Resource Definition

The Enterprise Server for .NET Administration UI is used to create, modify and delete database XA resource definitions. Database XA resource definitions are persisted in the cross-region database. To create a database XA resource definition:
  1. In the Tree pane under System, click XA Resource Definitions. 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 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 database XA resource definition:
    1. Click 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 Add > Database XA Resource Definition. See 2 in the diagram below.

      The New Database 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. Select the database provider. See 3 in the diagram below.
    5. A connection string now needs to be associated with the definition. To do this, click the button at the end of the Connection String field. See 4 in the diagram below.

      The Edit Connection String dialog is now displayed.
    6. 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 the Change button at the end of the Provider field.

      Alternatively, you can import a connection string that has previously been created by the HCOSS Connection Editor from either the machine.config or an HCOSS connection string export file. See 5 in the diagram below.

      Once you have provided all the information required for your database connection string, you can verify that it works by clicking the Test Connection button. Click OK to complete the creation of the connection string and return to the New Database XA Resource Definition dialog. See 6 in the diagram below.

    7. Click OK to dismiss the New Database XA Resource Definition dialog and complete the creation of the definition.
    8. Click 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 additionally configured for the XA resource definition.

Parent topic: Configuring XA resources
Related tasks
To Create an MQ XA Resource Definition
To Associate a Database XA Resource with a CICS Region Startup File
To Associate a Database XA Resource with a SIT
To Associate a Database XA Resource with a PCT
To Associate an MQ XA Resource with a CICS Region Startup File
To Associate an MQ XA Resource with a SIT
seexadef: administer XA resource definitions
Related information
About XA Resources
Configuring XA resources


To Create an MQ XA Resource Definition

The Enterprise Server for .NET Administration UI is used to create, modify and delete MQ XA resource definitions. MQ XA resource definitions are persisted in the cross-region database. To create an MQ XA resource definition:
  1. In the Tree pane under System, click XA Resource Definitions. 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 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 MQ 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 Add > MQ XA Resource Definition. See 2 in the diagram below.

      The New MQ 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. Enter the MQ queue manager name, MQ channel name and MQ connection name in the Queue manager name, Channel and Connection name fields respectively.
    5. Click OK to dismiss theNew MQ XA Resource Definition dialog and complete the creation of the definition. See 3 in the diagram below.

    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. The property values of the definition can be modified here if required.

Parent topic: Configuring XA resources
Parent topic: WebSphere MQ
Related tasks
To Create a Database XA Resource Definition
To Associate a Database XA Resource with a CICS Region Startup File
To Associate a Database XA Resource with a SIT
To Associate a Database XA Resource with a PCT
To Associate an MQ XA Resource with a CICS Region Startup File
To Associate an MQ XA Resource with a SIT
seexadef: administer XA resource definitions
WebSphere MQ
To Configure a CICS Trigger Monitor
To MQ Enable a JES Region
Related information
About XA Resources
Configuring XA resources


SEP Recycling

Overview

A SEP in Enterprise Server for .NET is implemented as a .NET Application Domain (AppDomain). AppDomains are used because they provide an isolation boundary for security, reliability and for unloading assemblies. Enterprise Server for .NET manages a pool of AppDomains, so that when it receives a request to run a CICS transaction or batch job, it takes an AppDomain from its pool and runs the request within it. When the request completes, and there is no request on the request queue ready for immediate execution, the AppDomain is returned to the pool. If there is a request ready to be executed, the AppDomain is immediately reused to execute it.

Once an assembly is loaded into an AppDomain, it cannot be unloaded until the AppDomain itself is unloaded. This means that if a new version of a program gets deployed, it will not get picked up and used by any existing AppDomain that has an earlier version of it loaded. The following sections describe how AppDomains (SEPs) may be recycled.

CICS SEP Recycling

Two options are available. You can either run the cpmt newcopy|phasein <program name> transaction, or run the seesys -phasein -program:<program name> command.

JES SEP Recycling

When a batch job runs, the AppDomain that is assigned to run the job runs the JES engine which coordinates the allocation of resources and driving of the individual job steps. The execution of the individual job steps occurs within a child AppDomain of the AppDomain running the JES engine (i.e. when a job executes under Enterprise Server for .NET, there are two AppDomains involved in its execution - one for the JES engine, the other for the job steps). By default, at the end of each job, the child AppDomain that has been used to run the job steps gets unloaded. This means that if new versions of any programs that have been loaded by the job steps get redeployed, the next time a job is run by the JES engine in the same AppDomain, the new versions of the programs will be used in the child AppDomain it creates to run the job steps in. This behavior is beneficial while developing your applications when programs need to be regularly recompiled and redeployed.

However, recycling the child AppDomain at the end of each job does incur a performance overhead. First, instantiating an AppDomain is not cheap and results in the COBOL run-time system and the job step execution environment needing to be initialised. Secondly, all programs used by the job steps will need to be loaded from their deployment locations. To avoid this performance overhead, which will be especially important in a production environment, the JES region can be configured so that the child AppDomains do not get unloaded at the end of each job, but instead only get unloaded after a certain period of time, or when the region running the job is different from the previous region, or never.

When a JES region is configured so that child AppDomains do not get unloaded at the end of each job, you can run the seesys -phasein -program:<program name> command to unload those AppDomains that have the given program loaded.

Explicit SEP Recycling

This may need to be done periodically to reduce the memory footprint of the processes that are hosting the SEPs. The seesys -recycle command is used to do this.

  • To Configure SEP Recycling for a JES Region
Parent topic: General Administration
Related tasks
To Configure SEP Recycling for a JES Region
seesys: administer a running system


To Configure SEP Recycling for a JES Region

To configure the recycling strategy of the AppDomains used for running job steps in a JES region:
  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 number 1 in the diagram below. A properties window is now displayed to the right-hand side of the Results pane.
  3. Locate the Recycling category in the properties window and select the Strategy property. If the property's Default value is selected, this will result in the AppDomain used to run a job's steps to be recycled at the end of each job. If the property's Configurable value is selected, you can then additionally specify the time period after which the job steps AppDomain is recycled, or whether the AppDomain is recycled after a region switch. If neither a time period nor a region switch are specified, the job steps AppDomain will only be unloaded when a seesys -recycle|-phasein command is run. See number 2 in the diagram below.
  4. Click either File > Save, or the Save icon in the toolbar to save the file. See number 3 in the diagram below.

You must cold-start the region for the changes to take effect.
Parent topic: SEP Recycling
Related tasks
SEP Recycling
seesys: administer a running system


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
  • seedup: retrieve trace table entries.
  • seelistener: start, stop, or dynamically configure a communications listener
  • seegetmi: Get machine information
  • seehsf: Historical Statistics Facility (HSF) administration
  • seemmc: launch the Microsoft Management Console (MMC) SEE Administration UI
  • seemmcconfig: manage the Microsoft Management Console (MMC) region definitions
  • seemonitor: start an event monitor
  • seeseccfg
  • seestart: start a region
  • seestop: stop a region
  • seesys: administer a running system
  • seeupgrade: upgrade from an earlier version
  • seewcfutil : Windows Communication Framework configuration
    Configure the WCF parameters .
  • seexadef: administer XA resource definitions
  • 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)
  • Data files, VSAM and fixed and line sequential file types.

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.

  • Data

    The action acted upon is a VSAM, line sequential or fixed length sequential file.

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, or for the data category with VSAM or sequential files.

create parameters

url
The name of the new or existing database in URL format.
name
The name of the table to create.

add action

Syntax:

  • 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
  • For Data category:
    seedeploy [option] data  add file sql://host/[/inst]/datastore/filename?[folder=path][;type=type][;reclen=min,max]

Adds an item to the database or Azure cloud drive. You can use wildcards in the filename to add multiple files for database targets, but not currently for Azure cloud drives.

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.

add parameters

file
The path and filename of the file to be loaded. Filenames can include wildcards to specify multiple files.
Url
See the section below on URL syntax.

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.

Syntax:

seedeploy [Option] [category] delete url#name

delete parameters

URL

The item to delete's database location in URL format.

See the section below on URL syntax.

extract action

Extracts the contents of the specified item to a file. The name part of the URL must include the file type.

Syntax:

  • 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

extract parameters

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.

See the section below on URL syntax.

FullFilePath

The full path to the file to be extracted.

list action

Lists the contents of the specified table. Use the -verbose to display additional information.

Syntax:

seedeploy [Option] [category] list url
Note: The list format is different for binary and rdo/ resdef resources. The -verbose option displays additional columns.

list parameters

URL

The database location in URL format of the item to be extracted.

See the section below on URL syntax.

Examples:

  • Create
    • The following command creates a new VSAM datastore in the database on the host\inst database server instance.
      seedeploy data create sql://host/inst/VSAM
  • Add
    • 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)
    • The following command deploys a VSAM file employee.dat to a datastore on the myhost\inst1 database server instance:.
      seedeploy data add c:\datadir\employee.dat sql://myhost/inst1/datastore/employee.dat?folder=VSAMFILES
    • The following command deploys a line sequential file employee.seq to a datastore on the myhost\inst1 database server instance:.
      seedeploy data add c:\datadir\employee.seq sql://myhost/inst1/datastore/employee.seq?folder=SEQFILES;type=lseq;reclen=0,132
    • The following command deploys a fixed length sequential file employee1.seq to a datastore on the myhost\inst1 database server instance:.
      seedeploy data add c:\datadir\employee1.seq sql://myhost/inst1/datastore/employee1.seq?folder=SEQFILES;type=seq;reclen=80,80
    • 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
    • The following command deletes 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 deletes ACCT00.DLL from the Azure cloud drive.
      seedeploy clouddrive delete cdrv://example.cloudapp.net/m:/programfolder/transactions/ACCT00.DLL
  • Extract
    • 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
    • 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

URL Syntax

SQL urls are constructed by placing a "sql://" or "cdrv://" followed by a mixture of the following syntax:

'clouddrive' category: cdrv://userid:password@servername/fullpath
  • userid - user login name as defined in monitor deployment setting
  • password - user password as defined in monitor deployment settings
  • Server - Name (may be "localhost")
  • fullpath - full pathname of file on Azure drive, e.g. m:\temp\testfile.dat
'binary' category: sql://server[/instance]/database/table[#key]
  • server - server hostname (may be "localhost")
  • instance - optional instance name
  • database - database name
  • table - table name
  • key - row primary key value

URLs for the "create" and "list" commands do not use keys.

URLs for other commands must have a key.

'rdo' category: sql://server[/instance]/database[/filename]

In the add command, a filename can be omitted, and the uploaded filename will be derived from the source filename.

  • server - server hostname (may be "localhost")
  • instance - optional instance name
  • database - database name. Must be '(crdb)' or '(crossRegionDatabase)'
  • filename - resource definition, region startup, or data file name

URLs for the "list" commands do not use filename.

URLs for other commands, except the data category, must have a filename.

'regionfile' category: sql://server[/instance]/database[/filename]

In the add command, a filename can be omitted, and the uploaded filename will be derived from the source filename

  • server - server hostname (may be "localhost")
  • instance - optional instance name
  • database - database name. Must be '(crdb)' or '(crossRegionDatabase)'
  • filename - resource definition, region startup, or data file name

URL's for the "list" commands do not use filename.

URL's for other commands, except the data category, must have a filename.

'data' category:

For an add, delete, or extract operation, the URL must take the form: sql://host[/instance]/datastore/filename[?folder=/path]

For a create or list operation, the URL must be of the form: sql://host[/instance]/datastore[?folder=/path]
  • server - server hostname (may be "localhost")
  • instance - optional instance name
  • datastore - datastore name
  • filename - resource definition, region startup, or data file name
  • path - name of folder to contain the file name in the datastore. It may have multiple parts. For example:
    • ...?folder=/MyDir
    • ...?folder=/MyDir/SubDir
  • For the add operation, the following attributes can be used:
    • type - the type of data object. Valid values are:
      • blob - blob types
      • lseq - line sequential file
      • seq - fixed length sequential file.
    • reclen - the min,max lengths of the sequential file.
      • ....;type-lseq;reclen=0,80

Example URLs:

  • sql://localhost/SEEApps/Programs
    • The table Programs in the database SEEApps, in the default instance on the local machine
  • sql://host/SQLEXPRESS/ACCT/Maps#ACCTSET
    • The binary with the key ACCTSET in the table ACCT in the instance SQLEXPRESS on host.
  • sql://localhost/SQLEXPRESS/(crdb)/ResourceDefinitions
    • The resource definition file with the name ResourceDefinitions in the cross-region database for the instance SQLEXPRESS on the local machine
  • sql://localhost/SQLEXPRESS/datastore/myseqfile?folder=/SEQFILES;type=seq;reclen=80,80
    • A fixed length 80 character per record, sequential file called myseqfile in folder /SEQFILES in a database called datastore
  • sql://localhost/SQLEXPRESS/datastore/myvsamfile?folder=/VSAM
    • A VSAM file called myvsamfile in the datastore database in a folder called VSAM
  • sql://localhost/SQLEXPRESS/binarystore/mytran.dll?folder=/applications;type=blob
    • A binary blob containing a dll called mytran.dll in a database called binarystore
  • cdrv://testuser:testpass@testhost.cloudapp.net/m:/programs/transact.dll
    • The transaction file called transact.dll in the programs directory on the azure drive mounted as m: in an azure deployment at testhost.cloudapp.net, using user id testuser and password testpass.

Special URLs:

Use e.g. "sql://server[/instance]/(regionDatabase)/ESDEMO/Programs" or "sql://server[/instance]/(rdb)/ESDEMO/Programs" for the Programs table in the ESDEMO region's region database.

Use "sql://host[/instance]/(crossRegionDatabase)" or"sql://host[/instance]/(crdb)" for the Binaries table in the cross-region database.

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


seedup: retrieve trace table entries.

Syntax

seedup parameter parameter . .

Retrieves diagnostic trace table entries from running SEPs in a region.

When work is performed by a region, the SEPs insert diagnostic information into memory-based local trace tables. The seedup command harvests these trace tables and brings them together into a single output file. An event monitor process is used to broker the requests to the SEPs, to return their local trace table information.

By default, the event monitor on the local machine is used to retrieve trace tables for all SEPs for all regions. However, you can use command line parameters to customize this process.

Parameters

-nobanner
Do not display utility welcome and copyright messages.
-region:<region-name>

Name of the region to retrieve trace entries from.

-server:<machine-name>[:<port>]
The name of the machine where an event monitor is running, that will co-ordinate the trace retrieval process. 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

seedup
- Generates local trace table output from all SEPs for all regions
seedup -usedb:(local)\SQLEXPRESS -region:ESDEMO
- Generates local trace table output from all SEPs for the ESDEMO region residing in the (local)\SQLEXPRESS database server instance.
seedup -region:ESDEMO
Generates local trace table output from all SEPs for the ESDEMO region residing in the default database server instance.
Parent topic: General Command Line Utilities


seelistener: start, stop, or dynamically configure a communications listener

Syntax

seelistener [action] options

This command can be used to start, stop, or dynamically configure a communications listener.

Actions

-add -channel:name
Add listener channel
-delete -channel:name
Delete listener channel
-disable -channel:name
Disable listener channel
-dump
Output raw listener configuration
-enable -channel:name
Enable listener channel
-i
Install seelistener service
-list
List available listeners
-list -channel
List available channels
-start
Start a listener (default action)
-stop
Stop a listener
-u
Uninstall seelistener service

Options

-configfile:file-name
Listener configuration file (-start, -i)
-disable
Disable the channel (-add)
-disconnect
Disconnect active sessions (-disable)
-dispatcher:URL
Dispatcher to communicate with (-add, -start)
-enable
Enable the channel (-add)
-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 is the preferred method.
Note: When running in the Azure cloud, we recommend configuring a heartbeat time of 30 seconds.
-listener:URL
Listener to communicate with (-add, -delete, -list -channel, -dump, -disable -channel:, -enable -channel:, -stop)
-nobanner
Do not display utility welcome and copyright messages
-out:output-file
Output file name (-dump)
-port:port-number
Channel port number required for the "tn3270", "mfbinp" and "mq" protocols (-add)
-protocol:protocol-name
Channel protocol - "tn3270", "mfbinp", "mq" or "p2p" (-add)
-qmname:qm-name
Queue manager name, optionally required for the "mq" protocol (-add)
-queue:queue-name
Initiation queue name, required for the "mq" protocol (-add)
-region:region-name
Start listener configured with default channels for just this region. Configuration file is not processed (-add, -delete, -list -channel, -start, -disable -channel:, -enable -channel:)
-server:machine[:port]
Machine and port of JES region listener. Default: -server:localhost:9022 (-list)
-service_account:Windows service account type
The type of Windows service account the seelistener service is to run under. The account type should be one of "localservice", "networkservice", "localsystem", or "user". Default: -service_account:localsystem (-i)
-service_password:password
The password of the user under which the seelistener service is to run. Used with -service_account:user and -service_username:xxx (-i)
-service_startup:Windows service startup type
The startup type of the seelistener service. The startup type should be one of "manual", "automatic" or "disabled" (-i)
-service_username:user-id
The user under which the seelistener service is to run. Used with -service_account:user and -service_password:xxx (-i)
-usedb
Use the default SQL Server instance (-add, -delete, -list, -list channel, -start, -disable -channel:, -enable -channel:)
-usedb:instance
Use the specified SQL Server instance (-add, -delete, -list, -list -channel, -start, -disable -channel:, -enable -channel:)
-verbose
The command output displays all of the messages that the command generates
-was
Use a WAS hosted dispatcher. Ignored if -dispatcher:<URL> is specified (-start)

Using a configuration file with seelistener

By default, the seelistener.exe.config file that resides in the same folder location as seelistener.exe is used to configure seelistener behavior. The configuration file specifies database connections, regions, communications channels and their options, WCF service connection options, and CTF tracing settings. If you do not want seelistener.exe to use the default configuration file, specify an alternative file using the -configfile option.

Installing and Running seelistener as a Windows Service

seelistener is installed as a Windows service as part of the Enterprise Server for .NET product installation. It is configured to run under the localsystem account with -service -nobanner -was set as its default command-line options. If you want to run the service under a different account, or with a custom configuration file, you must first uninstall it using:
seelistener -u
and then re-install specifying the required account and/or custom configuration file. For example:
seelistener -i -service_username:mydom\me -service_password:xxx -configfile:c:\mydir\my.listener.config
will install the seelistener service to run under the user mydom\me with the custom configuration file c:\mydir\my.listener.config.

Examples

Start the listener with the configuration being picked up from seelistener.exe.config:

seelistener

Start the listener with the configuration being picked up from c:\mydir\listener.config:

seelistener -configfile:c:\mydir\listener.config

Install the listener as a Windows service:

seelistener -i

Uninstall the listener Windows service:

seelistener -u

List all registered listeners (uses the local event monitor):

seelistener -list

List all registered listeners (uses the event monitor on the machine named OTHERMC):

seelistener -list -server:OTHERMC

List all channels for the ESDEMO region associated with the MYSS database server instance configured for the given listener:

seelistener -list -channel -region:ESDEMO -usedb:MYSS -listener:net.tcp//MYMC:9186/...

Output the raw channel configuration for the given running listener to the standard output device:

seelistener -dump -listener:net.tcp//MYMC:9186/...

Output the raw channel configuration for the given running listener to the file named c:\mydir\my.config:

seelistener -dump -out:c:\mydir\my.config -listener:net.tcp//MYMC:9186/...

Disable the channel named ABC for the ESDEMO region associated with the MYSS database server instance configured for the given listener:

seelistener -disable -channel:ABC -region:ESDEMO -usedb:MYSS -listener:net.tcp//MYMC:9186/...

Enable the channel named ABC for the ESDEMO region associated with the MYSS database server instance configured for the given listener:

seelistener -enable -channel:ABC -region:ESDEMO -usedb:MYSS -listener:net.tcp//MYMC:9186/...

Add the TN3270 channel named X specifying port 9813 for the ESDEMO region associated with the MYSS database server instance to the given listener:

seelistener -add -channel:X -protocol:tn3270 -port:9813 -usedb:MYSS -region:ESDEMO -listener:net.tcp//MYMC:9186/...

Add the MQ channel named Y specifying the initiation queue named INITQ and queue manager named QMA for the ESDEMO region associated with the MYSS database server instance configured to the given listener:

seelistener -add -channel:Y -protocol:mq -queue:INITQ -qmname:QMA -usedb:MYSS -region:ESDEMO -listener:net.tcp//MYMC:9186/...

Delete the channel named ABC for the ESDEMO region associated with the MYSS database server instance configured for the given listener:

seelistener -delete -channel:ABC -region:ESDEMO -usedb:MYSS -listener:net.tcp//MYMC:9186/...

Stop the given listener:

seelistener -stop -listener:net.tcp//MYMC:9186/...
Parent topic: General Command Line Utilities


seegetmi: Get machine information

Syntax

seegetmi parameter parameter . .

Retrieves the machine event logs, TCP usage, and process information from machines.

The seegetmi command harvests this information and places them into a set of files prefixed by the machine name from which they were obtained. An event monitor process is used to broker the requests.

By default, the event monitor on the local machine is used to retrieve the information from all machines that have an event monitor on them which are registered in the cross region database. However, you can use command line parameters to customize this process.

Parameters

-nobanner
Do not display utility welcome and copyright messages.
-server:<machine-name>[:<port>]
The name of the machine where an event monitor is running, that will co-ordinate the trace retrieval process. 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.
seegetmi -usedb:(local)\SQLEXPRESS
- Generates machine information output from all event monitors registered in the cross-region database. It uses the local event monitor to broker the requests.
Parent topic: General Command Line Utilities


seehsf: Historical Statistics Facility (HSF) administration

Syntax

seehsf [action] options

This command can be used to administer a CICS region's HSF data.

Actions

The following mutually-exclusive command-line actions are available for use with the seehsf command. The -aggregate action is assumed if no action is explicitly specified.
-aggregate
Generates data aggregated by transaction or job. Default action if no other action specified.
-delete -all
Delete all HSF data from the region database.
-delete -before:time
Delete HSF transaction data from the region database. All data for transactions or jobs which started before the specified time will be deleted from the region database.
-delete -keep:n
Delete HSF transaction data from the region database. Data for all but the latest n transactions or jobs will be deleted from the region database (i.e. Data for n transactions or jobs will be kept).
-info
Output information about the HSF data (number of transactions or jobs, and the time range for all transactions or jobs).
-raw
Generates data for each transaction or job, including job step data for JES regions.
-timegroup
Generates transaction or job data grouped into time blocks.

Options

For the -aggregate, -raw and -timegroup actions:
-count:n
Number of transactions or jobs to produce data for. Data will only be produced for the most recent n transactions or jobs.
-endtime:time
An upper bound on time. Data will not be produced for transactions or jobs which finished after this time. Defining a time range will reduce the time taken to generate the data.
-out:output filename
Output file name for data, in CSV format. Default: seehsf.csv.
-starttime:time
A lower bound on time. Data will not be produced for transactions or jobs which were queued before this time. Defining a time range will reduce the time taken to generate the data.
For the -raw action:
-filedata
Output data for CICS file APIs or JES file records
  • CICS only
    -filemax:n
    Maximum number of files to output data for. The most heavily used files will be displayed first. If n is set to 0, all files will be displayed (not compatible with -files:<n>). Default: 5.
    -files:list
    A comma-separated list of specific files to output data for (not compatible with -filemax:<n>).
    -tdqdata
    Include data for the CICS TDQ APIs in the output.
    -tdqmax:n
    Maximum number of TDQs to output data for. The most heavily used TDQs will be displayed first. If n is set to 0, all TDQs will be displayed (not compatible with -tdqs:<n>). Default: 5.
    -tdqs:list
    A comma-separated list of specific TDQs to output data for (not compatible with -tdqmax:<n>).
    -transaction:tran-id
    A specific transaction to output data for.
    -tsqdata
    Include data for the CICS TSQ APIs in the output.
    -tsqmax:n
    Maximum number of TSQs to output data for. The most heavily used TSQs will be displayed first. If n is set to 0, all TSQs will be displayed (not compatible with -tsqs:<n>). Default: 5.
    -tsqs:list
    A comma-separated list of specific TSQs to output data for (not compatible with -tsqmax:<n>).
  • JES only
    -jobname:name
    The name of a specific job to output data for
For the -timegroup action:
-emptyrows
Include empty rows (time intervals where there is no transaction or job data) in the output
-timeinterval:interval units
Time interval units. Either "seconds" or "minutes". Default: minutes.
  • CICS only
    -transactions:list
    A comma-separated list of transaction-ids to output specific data for, in addition to data for all transactions. Default: Combined transaction data is output.
  • JES only
    -jobs:list
    A comma-separated list of job names to output specific data for, in addition to data for all jobs Default: Combined job data is output
For all actions:
-nobanner
Do not display utility welcome and copyright messages.
-region:region-name
Name of region to administer HSF data for.
-usedb
Use the default SQL Server instance. Default: (local).
-usedb:instance
Use the specified SQL Server instance. Default: (local).
-utc
All datetime inputs will be interpreted as UTC, and all datetimes will be output in UTC. If omitted, all datetime inputs and outputs will be in the local timezone.
-verbose
The command output displays all of the messages that the command generates.

Examples

Custom output location/region/database:

seehsf -out:myFileName.csv -region:MYREGION -usedb:myServerName\myDb

Data (default: aggregated) for last 1000 transactions/jobs:

seehsf -count:1000

Data (default: aggregated) for transactions/jobs in a specified time range:

seehsf -starttime:2015-05-11 -endtime:2015-05-18

Raw data with file, TDQ, and TSQ data:

seehsf -raw -filedata -tdqdata -tsqdata

Raw data for a specific transaction and file:

seehsf -raw -transaction:ABCD -filedata -files:MYFILE

Raw data for a specific job, including file records:

seehsf -raw -region:JCLDEMO -jobname:MYJOB -filedata

Time-grouped data (1 minute time blocks by default):

seehsf -timegroup

Time-grouped data with a specified transaction list (1 second time blocks):

seehsf -timegroup -timeinterval:seconds -transactions:ACCT,MYTR

Time-grouped data with a specified jobs list:

seehsf -timegroup -region:JCLDEMO -jobs:JOB001,JOB002,JOB003

Deleting data from jobs/transactions before a specified date/time:

seehsf -delete -before:2015-05-30T12:30

Deleting all but the latest 1000 HSF transaction/job records from the region database:

seehsf -delete -keep:1000
Parent topic: General Command Line Utilities
Related tasks
Historical Statistics Facility (HSF)
To Enable HSF for a CICS Region
To View and Administer HSF Data for a CICS Region


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\5.0 \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


seemmcconfig: manage the Microsoft Management Console (MMC) region definitions

Syntax

seemmcconfig
             -add options
             -delete options
             -export options
             -import options
             -list

This command is used to administer the Enterprise Server for .NET Administration UI's region definitions configuration.

Actions

-add
Add a new region definition to the configuration used by the Enterprise Server for .NET Administration UI on the local machine.
-delete
Delete a region definition from the configuration used by the Enterprise Server for .NET Administration UI on the local machine.
-export
Export all region definitions from the configuration used by the Enterprise Server for .NET Administration UI on the local machine.
-import
Import region definitions into the configuration used by the Enterprise Server for .NET Administration UI on the local machine.
-list
List all region definitions from the configuration used by the Enterprise Server for .NET Administration UI on the local machine.

Options

-in:<input-file>
Input filename (-import)
-out:<output-file>
Output filename (-export)

Default : -out:regions.xml

-properties:<properties-file>
Properties file to use for region start-up (-add)
-region:<region-name>
Region name (-add, -delete)
-regionfile:<region-startup-file-name>
Region start-up filename (-add)
-server:<machine>
Hostname of the system that will perform region start-up (-add)

Default : -server:localhost

-type:cics | jcl | jes
Type of region being defined. jcl and jes are synonymous (-add)
-usedb
Use the default SQL Server instance (-add, -delete)
-usedb:<database-server-instance>
Use the specified SQL Server instance (-add, -delete)

Examples

  1. Export all of the currently configured regions used by the Enterprise Server for .NET Administration UI on the local machine to regions.xml in the current directory
    seemmcconfig -export
  2. Export all of the currently configured regions used by the Enterprise Server for .NET Administration UI on the local machine to c:\mydir\myregions.xml
    seemmcconfig -export -out:c:\mydir\myregions.xml
  3. Import the region definitions from c:\mydir\myregions.xml to the configuration used by the Enterprise Server for .NET Administration UI on the local machine
    seemmcconfig -import -in:c:\mydir\myregions.xml
  4. Add the region definition for the CICS region named TEST. The region database will reside on the default SQL Server instance. The region start-up file associated with the region is named test.config and resides in the cross-region database
    seemmcconfig -add -region:TEST -type:cics -regionfile:crdb:test.config
  5. Delete the region definition for the region named TEST which resides on the localhost\SQLEXPRESS SQL Server instance
    seemmcconfig -delete -usedb:localhost\SQLEXPRESS -region:TEST
  6. List all region definitions that are configured for the Enterprise Server for .NET Administration UI on the local machine
    seemmcconfig -list
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.
-service_account:Windows service account type
The type of Windows service account the seemonitor service is to run under. The account type should be one of "localservice", "networkservice", "localsystem", or "user". Default: -service_account:localsystem (-i)
-service_password:password
The password of the user under which the seemonitor service is to run. Used with -service_account:user and -service_username:xxx (-i)
-service_startup:Windows service startup type
The startup type of the seemonitor service. The startup type should be one of "manual", "automatic" or "disabled" (-i)
-service_username:user-id
The user under which the seemonitor service is to run. Used with -service_account:user and -service_password:xxx (-i)
-u
Uninstall the seemonitor Windows service.
-verbose
The command output displays all of the messages that the command generates.

Installing and Running seemonitor as a Windows Service

seemonitor is installed as a Windows service as part of the Enterprise Server for .NET product installation. It is configured to run under the localsystem account with -service -nobanner set as its default command-line options. When running in a scaled-out configuration, you will need to run the seemonitor service as a user with sysadmin privileges to each of the region and cross-region databases used by the configuration. If you want to run the service under a different account you must first uninstall it using:
seemonitor -u
and then re-install specifying the required account. For example:
seemonitor -i -service_username:mydom\me -service_password:xxx
will install the seemonitor service to run under the user mydom\me.
Parent topic: General Command Line Utilities


seeseccfg

Syntax
 seeseccfg action options
This utility is used to configure and maintain security configurations and managers from the command line.

Actions

  • - create
    • Create or modify a security configuration or security manager definition in the database defined using command-line parameters
  • -delete
    • Delete a security configuration or security manager from the database
  • -export
    • Export one or more security configurations or security managers from the database to an XML file
  • -import
    • Import security configurations and/or managers from an XML file
  • -list
    • List security configurations and/or managers

Options

  • All actions:

    • -usedb
      • Use the cross-region database on the default SQL Server instance to host the SC resource definitions (default)

    • -usedb:<instance>

      • Use the cross-region database on the named SQL Server instance to host the SC resource definitions
    • -nobanner
      • Do not display the banner
    • -quiet
      • Display minimal output
  • For creating a security configuration or security manager (-create):
    • -name:<name>
      • Name of the security configuration or manager to be created (required)
    • -cache_limit:<value>
      • Set the Cache Limit value
    • -cache_ttl:<value>
      • Set the Cache Time-To-Live value
    • -configfile:<file>
      • Specify a file containing configuration text
    • -type:configuration|manager
      • Type of object to create (required)
  • For creating a security configuration (-create -type:configuration):
    • -allow_unknown_resources
      • Enable the Allow Unknown Resources option
    • -allow_unknown_users
      • Enable the Allow Unknown Users option
    • -create_audit_events
      • Enable the Create Audit Events option
    • -manager:<name>
      • Specify a security manager. May be used multiple times
    • -type:configuration
      • Create a security configuration
    • -use_all_groups
      • Enable the Use All Groups option
    • -verify_against_all
      • Enable the Verify Against All option
  • For creating a security manager (-create -type:manager):
    • -authorized_id:<string>
      • ID to use when connecting to the ESM
    • -connection:<string>
      • Connection path to the ESM-description:<string> Description of this security manager
    • -disable
      • Do not enable this security manager
    • -module:<name>
      • Name of the ESM module (required)
    • -password:<string>
      • Password to use when connecting to the ES
    • -type:manager
      • Create a security manager
  • For deleting security configurations or managers (-delete):
    • -name:<name>
      • Name of the security configuration or manager to be deleted (required)
    • -type:configuration|manager
      • Type of object to delete (required)
  • For listing security configurations or managers (-list):
    • -type:configuration|manager
      • Type of object to list. If omitted, both are listed.
  • For importing security configurations or managers from a file (-import):
    • -in:<file>
      • XML file containing definitions of security configurations and/or managers (required)
  • For exporting security configurations or managers to a file (-export):
    • -append
      • If the output file already exists, append to it rather than replacing it
    • -name:<name>
      • Name of the security configuration or manager to be exported. If omitted, all are exported.
    • -out:<file>
      • Name of the file to create or update (required)
    • -type:configuration|manager
      • Type of object to export (required if -name specified, otherwise optional)

Examples

  • List the security managers defined in the (local)\SQLEXPRESS database
  seeseccfg -list -type:manager -usedb:(local)\SQLEXPRESS
  • Create a security configuration named "Default" with all default values, and using the security manager named "test3".
seeseccfg -create -type:configuration -name:Default -manager:test3
  • Create a security manager in the ESDB instance on "host" with various parameters. The configuration text for the manager is read from the file secmgr.txt.
 seeseccfg -create -usedb:host\ESDB -type:manager -name:test3 -module:NullEsm -description:"Test manager #3" -disable
       -cache_limit:200 -cache_ttl:600 -configfile:secmgr.txt
  • Export all security configurations and managers from the cross-region database in the default database instance on the local system.
seeseccfg -export -out:definitions.xml
  • Import one or more definitions from the specified file.
 seeseccfg -import -in:definitions.xml
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\5.0\Data\Config
  • %ProgramData%\Micro Focus\Enterprise Developer\5.0\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\5.0\Config
  • %ProgramData%\Micro Focus\Enterprise Developer\5.0\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


seesys: administer a running system

Syntax

seesys
             -console options
             -em      options
             -phasein options
             -recycle options
             -seppool options
This command is used to administer a running Enterprise Server for .NET system. Functionality includes:
  • Listing and replying to pending console input requests.
  • Phasing in a new version of a program that has already been loaded by one or more SEPs. This will cause a SEP that has already loaded the program to be unloaded and replaced by a new SEP. A transaction or job that is currently running in a SEP that needs to be replaced will be allowed to complete before the SEP gets unloaded.
  • Recycling SEPs. This may need to be done periodically to reduce the memory footprint of the processes that are hosting the SEPs. A transaction or job that is currently running in a SEP that needs to be recycled will be allowed to complete before the SEP gets unloaded.
  • Listing of all active SEP pools in the running system.
  • Recovery of tasks running in SEP pools that have been orphaned when the machine in which they are running dies or gets unconditionally powered down.
  • Listing of all event monitors registered in the cross-region-database
  • Deletion of event monitors that are no longer active (i.e. their state is in doubt)

Actions

-console
List, or reply to, pending console input requests.
-em, -event_monitor
List registered event monitors, or delete a registered event monitor when its state is in doubt
-phasein
Phase in a program to a running Enterprise Server for .NET system.
-recycle
Recycle SEPs in a running Enterprise Server for .NET system.
-seppool
List active SEP pools, or recover orphaned tasks running in SEP pools when the machine in which they are running dies or gets unconditionally powered down.

Options

-delete
Delete a registered event monitor (-em, -event_monitor)
-id:<reply-id>
Console input request id (-console).
-list
List pending console input requests (-console), active SEP pools (-seppool), or registered event monitors (-em, -event_monitor) .
-nobanner
Do not display the banner, or -list column headers.
-program:<program-name>
Program name (-phasein).
-recover
Recover orphaned tasks running in the SEP pool (-seppool).
-region:<region-name>
Name of the region being administered (-console, -phasein, -recycle).
-reply:<reply text>
Reply to a console input request (-console).
-server:<machine-name>[:<port>]
The name of the machine running the event monitor that will coordinate the administration function. Specify <port> if the event monitor on the target machine is not listening on the default 9186 port.
The default is localhost:9186. (-phasein, -recycle)
-server:<machine-name>
Machine targetted for SEP pool recovery (-seppool -recover).
-url:<sep-pool-url>
URL targetted for SEP pool recovery (-seppool -recover).
-url:<event-monitor-url>
URL of event monitor to be deleted (-em -delete, -event_monitor -delete)
-usedb
Use the default SQL Server instance (-console, -em, -event_monitor, -phasein, -recycle).
-usedb:instance
Use the specified SQL Server instance (-console, -em, -event_monitor, -phasein, -recycle).

Examples

Recycle all of the SEPs for the region named MYREGION hosted on the database server instance named MYDBINST:

seesys -recycle -usedb:MYDBINST -region:MYREGION

Phase in the program named MYPROG for the region named MYREGION hosted on the database server instance named MYDBINST:

seesys -phasein -program:MYPROG -usedb:MYDBINST -region:MYREGION

List all pending console input requests for the region named MYREGION hosted on the database server instance named MYDBINST:

seesys -console -list -usedb:MYDBINST -region:MYREGION

Reply to the console input request with id 8 for the region named MYREGION hosted on the database server instance named MYDBINST:

seesys -console -id:8 -reply:"Hello world" -usedb:MYDBINST -region:MYREGION

List all SEP pool processes registered in the cross-region database on the database server instance named MYDBINST:

seesys -seppool -list -usedb:MYDBINST

Recover all orphaned tasks that are associated with SEP pool processes registered in the cross-region database on the database server instance named MYDBINST that were running on the machine named MYSERVER:

seesys -seppool -recover -usedb:MYDBINST -server:MYSERVER

List all event monitor processes registered in the cross-region database on the database server instance named MYDBINST:

seesys -em -list -usedb:MYDBINST

Delete the event monitor process with the given URL from the cross-region database on the default database server instance:

seesys -em -delete -url:net.tcp://MYMC:9186/MicroFocus/SEE/MonitorService/Endpoint -usedb
Parent topic: General Command Line Utilities
Related tasks
SEP Recycling
To Configure SEP Recycling for a JES Region


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\5.0\Data\Config
  • %ProgramData%\Micro Focus\Enterprise Developer\5.0\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


seexadef: administer XA resource definitions

Syntax

seexadef action options

This utility is used to create, delete and list XA resource definitions.

Action Parameter

-create
Create an XA resource definition.
-delete
Delete an XA resource definition.
-list
List XA resource definitions.

Options Parameter

  • All actions:
    -usedb
    Use the cross-region database on the default SQL Server instance to host the XA resource definitions (default).
    -usedb:<database-server-instance>
    Use the cross-region database on the named SQL server instance to host the XA resource definitions.
  • For creating database definitions (-create -type:db):
    -connstring:"<connection-string>"
    Database connection string
    Note: The connection string needs to be enclosed in double-quotes only if it contains spaces.
    -enlist
    Enlist the database connection in the global transaction (default).
    -name:<name>
    Name of the database XA resource definition to be created.
    -noenlist
    Do not enlist the database connection in the global transaction.
    -packagepath:<package-path-name>
    Name of the package path to be used for the connection.
    -packageset:<package-set-name>
    Name of the package set to be used for the connection.
    -plan:<application-plan-name>
    Name of the application plan to use for the connection.
    -provider:<provider-name>
    Name of the .NET database provider to be used for the connection (default System.Data.SqlClient).
    -region:<region-name>
    Name of the region to associate with the XA resource definition. If not specified, the XA resource definition will be associated with all regions.
    -type:db
    Database XA resource definition.
  • For creating MQ definitions (-create -type:mq):
    -channel:<channel-name>
    MQ channel name.
    -connname:<connection-name>
    MQ connection or machine name.
    -name:<name>
    Name of the MQ XA resource definition to be created.
    -qmname:<queue-manager-name>
    MQ queue manager name.
    -region:<region-name>
    Name of the region to associate with the XA resource definition. If not specified, the XA resource definition will be associated with all regions.
    -type:mq
    MQ XA resource definition.
  • For deleting XA resource definitions:
    -name:<name>
    Name of the MQ XA resource definition to be deleted.
    -region:<region-name>
    Name of the region associated with the XA resource definition. If not specified, the XA resource definition is assumed to be associated with all regions.
    -type:db|mq
    Database or MQ XA resource definition.
  • For listing XA resource definitions:
    -type:db|mq
    Database or MQ XA resource definitions. If omitted, both types of XA resource definitions will be listed.

Examples

seexadef -create -type:db -name:xyz -connstring:abcdefg
Creates a database XA resource definition named xyz with a connection string of abcdefg in the cross-region database of the default SQL Server instance.
seexadef -create -type:mq -name:abc -connname:mymc -qmname:QMA -channel:CQMA
Creates an MQ XA resource definition named abc with a connection name of mymc, queue manager name of QMA and channel name of CQMA in the cross-region database of the default SQL Server instance.
seexadef -delete -type:db -name:xyz
Deletes the database XA resource definition named xyz from the cross-region database of the default SQL Server instance.
seexadef -delete -type:mq -name:abc -region:ESDEMO
Deletes the MQ XA resource definition named abc associated with the ESDEMO region from the cross-region database of the default SQL Server instance.
seexadef -list
Lists both the database and MQ XA resource definitions that have been defined in the cross-region database of the default SQL Server instance.
seexadef -list -type:db
Lists the database XA resource definitions that have been defined in the cross-region database of the default SQL Server instance.
seexadef -list -type:mq
Lists the MQ XA resource definitions that have been defined in the cross-region database of the default SQL Server instance.
Parent topic: General Command Line Utilities
Related tasks
To Create a Database XA Resource Definition
To Create an MQ XA Resource Definition
To Associate a Database XA Resource with a CICS Region Startup File
To Associate a Database XA Resource with a SIT
To Associate a Database XA Resource with a PCT
To Associate an MQ XA Resource with a CICS Region Startup File
To Associate an MQ XA Resource with a SIT
Related information
About XA Resources
Configuring XA resources


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\5.0\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\5.0 \Config

  • %ProgramData%\Micro Focus\Enterprise Developer\5.0\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


Historical Statistics Facility (HSF)

Overview

When the Historical Statistics Facility (HSF) is enabled for an Enterprise Server for .NET CICS or JES region, event records are created in the region database at run time for transactions and jobs respectively. These records can be subsequently processed to provide detailed information of their execution. This information can include:
  • Number of times a transaction has been executed
  • Number of times a job has been executed
  • Time spent by a transaction within CICS APIs
  • Time spent by a transaction or job step within SQL APIs
  • Time spent by a transaction processing files
  • Time spent by a transaction processing TD and TS queues
  • Time spent processing a job and its steps
  • I/O counts for datasets used by job steps
  • Number of transactions executed per second

Region Configuration

The Region Startup File Editor is used to configure HSF for CICS and JES regions. You can specify whether HSF is to be enabled for the region, the lifetime of the HSF data, and whether HSF data is to be persisted across region cold-starts. HSF data will always be persisted across warm-starts. By default, HSF is not enabled for a region.

If a lifetime is configured for HSF data, a running Enterprise Server for .NET system will periodically delete any data that has expired the specified lifetime. HSF data can also be manually deleted using the Enterprise Server for .NET Administration UI or seehsf command-line tool.

Note: To ensure accuracy for transaction and job submission latency (i.e. the time between when a task is queued and when it goes into execution), the system clocks of any machines running SEPs and the machine hosting the region database should be synchronized. This does not mean that the system clocks of all of these machines have to be set in the same time zone; it is the underlying UTC time of the machines that is important to be synchronized.
Note: If a region was created with HSF enabled using a version of Enterprise Server for .NET earlier than 2.3 hot-fix 2, HSF will be implicitly disabled during region start-up if HSF data persistence has been enabled in the region start-up file. This can be resolved by doing one of the following:
  • Disable HSF data persistence and cold start the region
  • Drop the region database and cold start the region

Administering HSF

HSF can be administered by either the Enterprise Server for .NET Administration UI, or the seehsf command-line tool.

The Enterprise Server for .NET Administration UI's Historical Statistics Facility view for the currently selected region can be used to:
  • Configure the range of HSF data to be used to display statistics for (e.g. maximum number of transactions, maximum number of jobs, and start/end date/time)
  • Display the average latency and execution time, and the number of times executed of each transaction id or job name
  • Display the latency and execution time of each individual transaction or job executed
  • Delete HSF data from the region database
The seehsf command-line tool can be used to:
  • Create a .csv file containing data for each individual transaction instance. By default this data includes the latency time, execution time and time spent within CICS APIs. It can optionally additionally include the time spent processing files, TD queues and/or TS queues
  • Create a .csv file containing data aggregated for each transaction id. This data includes the number of times each transaction id has been executed, together with the average latency time, execution time and time spent within CICS APIs
  • Create a .csv file containing data grouped by time (e.g. showing the number of transactions executed per 1 minute interval)
  • Restrict the amount of data written to the .csv file by allowing the specification of the maximum number of records, maximum number of transactions, and start/end date/time
  • Delete HSF data from the region database
  • Display information about the HSF configuration for the region
Note: seehsf outputs times to the .csv file in the format hh:mm:ss.mmm (e.g. 10:35:58.734). Unfortunately Microsoft's excel spreadsheet program does not recognise this as a valid time format, resulting in the data being incorrectly displayed. To view the time data correctly, apply the following custom time format to the Time column:
hh:mm:ss.000
  • To Enable HSF for a CICS Region
  • To Enable HSF for a JES Region
  • To View and Administer HSF Data for a CICS Region
  • To View and Administer HSF Data for a JES Region
Parent topic: General Administration
Related tasks
To Enable HSF for a CICS Region
To View and Administer HSF Data for a CICS Region
seehsf: Historical Statistics Facility (HSF) administration
Related reference
seehsf: Historical Statistics Facility (HSF) administration


To Enable HSF for a CICS Region

The Historical Statistics Facility (HSF) needs to be enabled for an Enterprise Server for .NET CICS region to cause event records to be created at run time for transactions. These records can be subsequently processed to provide detailed information of their execution. To enable HSF:

  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 Historical Statistics Facility category in the properties window and set the value of the HSF Enabled property to true. HSF can be further configured by setting the values of one or more of the HSF Data Lifetime, Max HSF Transactions and Persist HSF Data properties. 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: Historical Statistics Facility (HSF)
Related tasks
Historical Statistics Facility (HSF)
To View and Administer HSF Data for a CICS Region
seehsf: Historical Statistics Facility (HSF) administration


To Enable HSF for a JES Region

The Historical Statistics Facility (HSF) needs to be enabled for an Enterprise Server for .NET JES region to cause event records to be created at run time for transactions. These records can subsequently be processed to provide detailed information of their execution. To enable HSF:

  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 Historical Statistics Facility category in the properties window and set the value of the HSF Enabled property to true. HSF can be further configured by setting the values of one or more of the HSF Data Lifetime, Max HSF Jobs and Persist HSF Data properties. 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: Historical Statistics Facility (HSF)


To View and Administer HSF Data for a CICS Region

The Historical Statistics Facility (HSF) needs to be enabled for an Enterprise Server for .NET CICS region before being able to view and administer the HSF data using the Enterprise Server for .NET Administration UI.

To view and administer HSF data:

  1. Select a CICS region from within the Enterprise Server for .NET Administration UI, and click on Historical Statistics Facility in the Action pane. See 1 in the diagram below. The Historical Statistics Facility view is displayed in the Results pane, but no HSF data is initially shown. This provides you with the opportunity to configure/ restrict the number and/ or range of HSF transactions that you want statistics to be displayed for. By default, the most recent 1000 transactions will be used.
  2. Click on the Refresh button to display the HSF data. See 2 in the diagram below.

  3. The HSF data is displayed as an alphabetical list of all the transaction ids that have executed for the configured number and/ or range of records. For each transaction id, the average latency, average execution time and the number of times executed is displayed. See 3 in the diagram below.

  4. Double-clicking on a transaction-id will display details for each individual invocation of it. See the diagram below.

    Click the Return button to return to the previous view showing the alphabetical list of transaction ids. See 4 in the diagram above.

  5. To configure/ restrict the number and/ or range of HSF data that you want statistics to be displayed for, click the Configuration button. See 5 in the diagram below.

    The Configure HSF dialog is displayed:

    In this dialog you can:
    • Specify the range of HSF data that you want statistics displayed for, by checking the Start Date and/ or End Date filters and selecting the required dates and times
    • Specify the maximum number of transactions that you want statistics displayed for, by checking the Maximum Records filter and entering the number of transactions you want to see
      Note: If Maximum Records is not specified, all transactions will be included
    Click OK to return to the Historical Statistics Facility view
    Note: You will need to refresh the Historical Statistics Facility view for the configured options to take effect
  6. To delete HSF data from the region database, click the Discard Records button. See 6 in the diagram below.

    The Discard HSF Records dialog is displayed:

    In this dialog you can:
    • Specify that all HSF data is deleted by checking Remove All
    • Specify the date and time before which all HSF data is deleted, by checking Remove Before and entering the date and time
    • Specify the most recent number of transactions in the HSF data to remain, by checking Remove All Records Except and entering the number of transactions
    Click OK to delete the HSF data and return to the Historical Statistics Facility view
    Note: Deleting a large number of records can take a very long time to complete. Using the seehsf command-line tool to do this may be preferable to blocking the UI while the delete operation is performed
Parent topic: Historical Statistics Facility (HSF)
Related tasks
Historical Statistics Facility (HSF)
To Enable HSF for a CICS Region
seehsf: Historical Statistics Facility (HSF) administration


To View and Administer HSF Data for a JES Region

The Historical Statistics Facility (HSF) needs to be enabled for an Enterprise Server for .NET JES region before being able to view and administer the HSF data using the Enterprise Server for .NET Administration UI.

To view and administer HSF data:

  1. Select a JES region from within the Enterprise Server for .NET Administration UI, and click Historical Statistics Facility in the Action pane. See 1 in the diagram below. The Historical Statistics Facility view is displayed in the Results pane, but no HSF data is initially shown. This provides you with the opportunity to configure/ restrict the number and/ or range of HSF jobs that you want statistics to be displayed for. By default, the most recent 1000 jobs will be used.
  2. Click Refresh to display the HSF data. See 2 in the diagram below.

  3. The HSF data is displayed as an alphabetical list of all the jobs that have executed for the configured number and/ or range of records. For each job, the average latency, average execution time and the number of times executed is displayed. See 3 in the diagram below.

  4. Double-clicking a job name will display details for each individual invocation of it. See the diagram below.

    Click Return to return to the previous view showing the alphabetical list of job names. See 4 in the diagram above.

  5. To configure/ restrict the number and/ or range of HSF data that you want statistics to be displayed for, click Configuration. See 5 in the diagram below.

    The Configure HSF dialog is displayed:

    In this dialog you can:
    • Specify the range of HSF data that you want statistics displayed for, by checking the Start Date and/ or End Date filters and selecting the required dates and times.
    • Specify the maximum number of jobs that you want statistics displayed for, by checking the Maximum Records filter and entering the number of jobs you want to see.
      Note: If Maximum Records is not specified, all jobs will be included.
    Click OK to return to the Historical Statistics Facility view.
    Note: You will need to refresh the Historical Statistics Facility view for the configured options to take effect.
  6. To delete HSF data from the region database, click Discard Records. See 6 in the diagram below.

    The Discard HSF Records dialog is displayed:

    In this dialog you can:
    • Specify that all HSF data is deleted by checking Remove All.
    • Specify the date and time before which all HSF data is deleted, by checking Remove Before and entering the date and time.
    • Specify the most recent number of jobs in the HSF data to remain, by checking Remove All Records Except and entering the number of jobs.
    Click OK to delete the HSF data and return to the Historical Statistics Facility view.
    Note: Deleting a large number of records can take a very long time to complete. You might prefer to use the seehsf command-line tool to do this rather than blocking the UI while the delete operation is performed.
Parent topic: Historical Statistics Facility (HSF)


WebSphere MQ

Overview

IBM WebSphere MQ, formerly known as MQSeries, is a messaging integration product that provides reliable, secure and, optionally, transactional message delivery. Enterprise Server for .NET uses the WebSphere MQ .NET managed code client to allow application programs to interact with an MQ server. However, as the WebSphere MQ .NET managed code client only provides a class library interface and not the traditional MQI (MQ programming interface), the MQI is implemented within Enterprise Server for .NET to allow applications that use the MQI to be able to run unchanged.

Supported Versions of the WebSphere MQ .NET Managed Code Client

  • WebSphere MQ 7.5.0.3 or later
  • WebSphere MQ 8.0 or later
Note: If two or more versions of the WebSphere MQ .NET managed code client have been installed side-by-side, Enterprise Server for .NET will load and use the most recent version.
The following features are not available to a WebSphere MQ .NET managed code client (please see IBM documentation for more details):
  • Channel compression
  • SSL support (now available in WebSphere MQ 8.0)
  • Channel exit chaining

MQI

The following MQI verbs, with some parameter restrictions, are supported by Enterprise Server for .NET:
Verb | Parameter | Support
MQBACK | Hconn | Full
CompCode | Full
Reason | Full
MQBEGIN | Hconn | Full
BeginOptions | Ignored
CompCode | Full
Reason | Full
MQCLOSE | Hconn | Full
CompCode | Full
Hobj | Full
Options | Full
Reason | Full
MQCMIT | Hconn | Full
CompCode | Full
Reason | Full
MQCONN | QMgrName | Full
Hconn | Full
CompCode | Full
Reason | Full
MQCONNX | QMgrName | Full
ConnectOpts
  • ClientConnOffset and ClientConnPtr fields used to address MQCD structure. The MQCD StrucId, Version, ChannelName, ChannelType and ConnectionName fields are honored, all other MQCD fields are ignored
  • All other fields ignored
Hconn | Full
CompCode | Full
Reason | Full
MQDISC | Hconn | Full
CompCode | Full
Reason | Full
MQGET | Hconn | Full
Hobj | Full
MsgDesc | Full
GetMsgOpts
  • StrucId, Version, Options, WaitInterval, ResolvedQName, MatchOptions, GroupStatus, SegmentStatus and Segmentation fields are honored
  • All other fields are ignored
BufferLength | Full
Buffer | Full
DataLength | Full
CompCode | Full
Reason | Full
MQINQ | Hconn | Full
Hobj | Full
SelectorCount | Full
Selectors | Full
IntAttrCount | Full
IntAttrs | Full
CharAttrLength | Full
CharAttrs | Full
CompCode | Full
Reason | Full
MQOPEN | Hconn | Full
ObjDesc
  • StrucId, Version, ObjectName, ObjectQmgrName, DynamicName and AlternateUserId fields are honored
  • ObjectType of type MQOT_Q (i.e. queue) supported. All other object types are unsupported
  • All other fields are ignored
Options | Full
Hobj | Full
CompCode | Full
Reason | Full
MQPUT | Hconn | Full
Hobj | Full
MsgDesc | Full
PutMsgOpts
  • StrucId, Version, Options, Context, KnownDestCount, UnknownDestCount, InvalidDestCount, ResolvedQname and ResolvedQmgrName fields are honored
  • All other fields are ignored
BufferLength | Full
Buffer | Full
CompCode | Full
Reason | Full
MQPUT1 | Hconn | Full
ObjDesc
  • StrucId, Version, ObjectName, ObjectQmgrName, DynamicName and AlternateUserId fields are honored
  • ObjectType of type MQOT_Q (i.e. queue) supported. All other object types are unsupported
  • All other fields are ignored
MsgDesc | Full
PutMsgOpts
  • StrucId, Version, Options, Context, KnownDestCount, UnknownDestCount, InvalidDestCount, ResolvedQname and ResolvedQmgrName fields are honored
  • All other fields are ignored
BufferLength | Full
Buffer | Full
CompCode | Full
Reason | Full
MQSET | Hconn | Full
Hobj | Full
SelectorCount | Full
Selectors | Full
IntAttrCount | Full
IntAttrs | Full
CharAttrLength | Full
CharAttrs | Full
CompCode | Full
Reason | Full
Note: The level of MQI support listed above is for the verbs and their interfaces as defined by the IBM documentation for the WebSphere MQ 7.5.0.3 and 8.0 releases. Any changes or extensions to these verbs made by IBM in later versions of WebSphere MQ are not currently supported.

Configuration

Both CICS and JES regions can be fully configured for MQ using the Enterprise Server for .NET Administration UI. If necessary, you can configure the MQ client externally via environment variables and/ or app.config files. However, if the MQ client is configured externally, you should bear the following in mind:
  • External configuration will apply to all regions
  • Each machine in a scale-out will require the environment variables set with the same MQ configuration for the seelistener.exe, w3wp.exe and seesep.exe (used when debugging) processes
  • Each machine in a scale-out will require the app.config files for seelistener.exe and seesep.exe (used when debugging) and web.config for w3wp.exe set with the same MQ configuration

A CICS region requires an MQ XA resource definition to be created using the XA Resource Definitions Editor, and its name specified in the region start-up file using the Region Startup File Editor. The MQ XA resource definition allows the MQ queue manager name, channel name and connection name to be specified. If trigger monitors are to be used, a listener channel for each trigger monitor needs to be configured using the Listener Configuration Editor. Each trigger monitor configuration requires the name of the MQ initiation queue to be specified.

A JES region requires the MQ channel and connection names, used when an application attempts to connect to a queue manager using the MQCONN or MQCONNX APIs, to be specified in the region start-up file using the Region Startup File Editor.

  • To Create an MQ XA Resource Definition
  • To Associate an MQ XA Resource with a CICS Region Startup File
  • To Associate an MQ XA Resource with a SIT
  • To Configure a CICS Trigger Monitor
  • To MQ Enable a JES Region
Parent topic: General Administration
Related tasks
To Create an MQ XA Resource Definition
To Associate an MQ XA Resource with a CICS Region Startup File
To Associate an MQ XA Resource with a SIT
To Configure a CICS Trigger Monitor
To MQ Enable a JES Region


To Associate an MQ XA Resource with a CICS Region Startup File

If transactions invoke MQ APIs, an MQ XA resource definition must be associated with the region to enable CICS to connect to the required MQ queue manager to which the APIs will be targeted. An MQ 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 MQ 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 MQ category in the properties window and enter the MQ XA resource definition name that you want associated with the region as the value of the MQ 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: WebSphere MQ
Parent topic: CICS Region Startup Files
Related tasks
To Create a Database XA Resource Definition
To Create an MQ XA Resource Definition
To Associate a Database XA Resource with a CICS Region Startup File
To Associate a Database XA Resource with a SIT
To Associate a Database XA Resource with a PCT
To Associate an MQ XA Resource with a SIT
seexadef: administer XA resource definitions
WebSphere MQ
To Configure a CICS Trigger Monitor
To MQ Enable a JES Region
Related information
About XA Resources
Configuring XA resources


To Associate an MQ XA Resource with a SIT

If transactions invoke MQ APIs, an MQ XA resource definition must be associated with the region to enable CICS to connect to the required MQ queue manager to which the APIs will be targeted. An MQ 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 MQ 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 MQ category in the properties window and enter the MQ XA resource definition name that you want associated with the SIT as the value of the MQ 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: WebSphere MQ
Parent topic: Defining and Configuring Resources
Related tasks
To Create a Database XA Resource Definition
To Create an MQ XA Resource Definition
To Associate a Database XA Resource with a CICS Region Startup File
To Associate a Database XA Resource with a SIT
To Associate a Database XA Resource with a PCT
To Associate an MQ XA Resource with a CICS Region Startup File
seexadef: administer XA resource definitions
WebSphere MQ
To Configure a CICS Trigger Monitor
To MQ Enable a JES Region
Related information
About XA Resources
Configuring XA resources


To Configure a CICS Trigger Monitor

A listener channel needs to be configured for each trigger monitor required by a CICS region. To configure a CICS trigger monitor:
  1. Open the listener configuration file using the Enterprise Server for .NET Administration UI's Listener Configuration Editor.
  2. Right-click the name of the region for which the CICS trigger monitor is to be created and selectAdd Channel > MQ. See 1 in the diagram below.

    The Add New MQ Listener Channel dialog is displayed.
  3. Enter the name of the listener channel, the name of the MQ initiation queue to be monitored and, optionally, the MQ queue manager name in the Name, Initiation queue name and Queue manager name (optional) fields respectively.
  4. Click OK to dismiss the Add New MQ Listener Channel dialog and complete the creation of the CICS trigger monitor listener channel. See 2 in the diagram below.

  5. Click the newly created listener channel in the Results pane. A properties window is now displayed to the right-hand side of the Results pane. The property values of the channel can be modified here if required.
  6. Click File > Save , or click the Save icon on the toolbar to save the listener configuration. See 3 in the diagram below.

You must (re-)start the listener for the changes to take effect.
Parent topic: WebSphere MQ
Related tasks
WebSphere MQ
To Create an MQ XA Resource Definition
To Associate an MQ XA Resource with a CICS Region Startup File
To Associate an MQ XA Resource with a SIT
To MQ Enable a JES Region


To MQ Enable a JES Region

A JES region requires the MQ channel and connection names, used when an application attempts to connect to a queue manager using the MQCONN or MQCONNX APIs, to be specified in the region start-up file. To do this:
  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 MQ category in the properties window and enter MQ channel name and MQ connection name in the Channel name and Connection name fields respectively. See 2 in the diagram below.
  4. Click 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: WebSphere MQ
Related tasks
WebSphere MQ
To Create an MQ XA Resource Definition
To Associate an MQ XA Resource with a CICS Region Startup File
To Associate an MQ XA Resource with a SIT
To Configure a CICS Trigger Monitor


System Monitoring and Recovery

Overview

Event monitors (seemonitor.exe processes) constantly monitor a running Enterprise Server for .NET system. If a SEP pool (w3wp.exe or seesep.exe) process dies for any reason (e.g. due to a StackOverflowException or a user decides to "Stop Debugging"), the event monitor running on the same machine will detect that and instigate the recovery of any orphaned running tasks from that process. All resources associated with an orphaned task are released (e.g. ENQ locks, initiators, or printers). See Local SEP Pool Recovery below.

Event monitors may also be configured to monitor the health of SEP pools running on other machines in an Enterprise Server for .NET scale-out. When configured in this way, an event monitor will check whether a SEP pool is still active as part of its periodic system health check, and if it deems that the SEP pool is no longer alive, it will instigate the recovery of any orphaned running tasks associated with it. See Remote SEP Pool Recovery below.

In rare circumstances it is possible that a request gets dispatched, but does not get associated with a SEP for execution (e.g. communication failure between dispatcher and SEP pool processes). Each time this happens, an available SEP is effectively allocated, until a point is reached where all SEPs are assigned and no further requests can get processed by the region. Such requests now get detected as part of the event monitor system health checking and re-dispatched to an available SEP. See Dispatched Request Recovery below.

An event monitor running on the same machine as a listener (seelistener.exe process) will also periodically check that the EZ listener associated with a region is still responsive. If it is not, the region's EZ listener is reset to allow subsequent EZ socket operations to be routed to a different listener process.

The Registered Event Monitors and Registered SEP Pools view in the Enterprise Server for .NET Administration UI are provided to allow the manual monitoring of the health of event monitors and SEP pools in the system respectively, and take action if an event monitor or SEP pool is deemed to be no longer active.

Local SEP Pool Recovery

An event monitor will automatically detect when a SEP pool process running on the same machine has died and instigate the recovery of any orphaned tasks. Messages indicating that a SEP pool has died and recovery has taken place will get written to the console of each region affected:
SEEEM0058W SEP pool process (Host: MY-MACHINE; PID:3868) terminated with orphaned tasks
SEEEP0173I SEP pool process (Host: MY-MACHINE; PID:3868) recovery started
SEEEP0174I SEP pool process (Host: MY-MACHINE; PID:3868) recovery completed
Corresponding Windows event log entries will also be created.

Remote SEP Pool Recovery

SEP pool processes periodically emit a heartbeat to indicate that they are still alive. When a SEP pool process stops emitting heartbeats it can be assumed that the machine on which it is running has either died, been powered down or has lost network connectivity. Any tasks that were running on a SEP pool no longer heartbeating will have been orphaned (e.g. a job previously running in the SEP pool would still appear Active in the Enterprise Server for .NET Administration UI's Spool view and hold resource locks, but no application would actually be running).

The Registered SEP Pools view in the Enterprise Server for .NET Administration UI can be used to manually detect when a SEP pool is no longer active. This view has a Status column that indicates whether the state of a SEP pool is:
  • Ok - the SEP pool is responsive and running normally
  • In doubt - no heartbeat has been issued by the SEP pool for over 10 seconds. The H/B (s) column indicates the number of seconds since the last heartbeat
  • Unknown - the SEP pool is running on a machine with a product version installed earlier than 2.3 update 2 hot-fix 4, and so does not support heartbeating. The SEP pool may be running normally, but the system cannot determine its state.
By selecting a SEP pool in the list and clicking on the Recover button, any orphaned tasks associated with the SEP pool will be recovered.
Note: The system will reject any recovery attempt of a SEP pool that is still actively heartbeating.
Note: Be very careful when attempting to recover a SEP pool in the Unknown state as it may still be active.
Event monitors can be configured to automatically recover SEP pools that are no longer heartbeating as part of their regular system health check cycle. The following settings are provided for inclusion in the MicroFocus.SEE.Monitor > general section of the seemonitor.exe.config file:
  • EM.HealthCheck.Interval - set the interval in seconds at which the event monitor will perform system health checking (default 20 seconds)
  • EM.SepPool.Recovery - set value to "true" or "yes" to enable automatic SEP pool recovery checking (default 'false')
  • EM.SepPool.Recovery.HeartbeatElapsed - set value to the minimum time in seconds since a SEP pool's last heartbeat after which the SEP pool is considered to be dead and needs recovering (default 10 seconds)
For example:
<MicroFocus.SEE.Monitor>
    <general>
      ...
      <add key="EM.HealthCheck.Interval" value="20" />
      <add key="EM.SepPool.Recovery" value="true" />
      <add key="EM.SepPool.Recovery.HeartbeatElapsed" value="10" />
      ...
    </general>
</MicroFocus.SEE.Monitor>
Messages similar to those for a local SEP pool recovery get written to the region console and Windows event log when an event monitor automatically recovers a SEP pool.

Dispatched Request Recovery

Event monitors will periodically check to see whether dispatched requests exist that have not been associated with a SEP for execution. By default, if at least 10 seconds has elapsed since the request has been marked active, the event monitor will cause it to be dispatched to an available SEP. The event monitor can be configured to specify a different elapsed time before re-dispatching by using the following setting in the MicroFocus.SEE.Monitor > general section of the seemonitor.exe.config file:
  • EM.ActiveRequest.Elapsed - set value to the minimum time in seconds before an active request that has not been dispatched to a SEP gets re-dispatched (default 10 seconds)
For example:
<MicroFocus.SEE.Monitor>
    <general>
      ...
      <add key="EM.ActiveRequest.Elapsed" value="15" />
      ...
    </general>
</MicroFocus.SEE.Monitor>
Parent topic: General Administration


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)
  • Minidumps
  • 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
$(RUNUNIT)
A unique number that represents the managed RunUnit ID (applies to COBOL only).
$(RUNUNIT_SESSIONNAME)
The session name passed to the managed RunUnit (applies to COBOL only).
$(RUNUNIT_GUID)
The globally unique identifier associated with the managed RunUnit (applies to 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. This is used when a trace file is created. 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 . 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 or ) 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 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
$(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. This is used when a trace file is created. 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


Minidumps

CICS and JES regions can be configured to create a Microsoft minidump file whenever an exception (including a COBOL run-time system error) occurs within a user application. A minidump file can be loaded into a debugger such as Visual Studio or windbg to identify where in the application code the exception has occurred.

Note: Although minidumps will be generated for both 32-bit and 64-bit processes, it is not always possible for exception details to be created for 32-bit minidumps. This is a known deficiency in the .NET framework's support for minidump creation. We therefore strongly recommend that you run ES for .NET on a 64-bit OS if you need to generate minidumps to diagnose run-time errors.

To enable a region for minidump creation, open the startup file of the CICS or JES region you are configuring, with the Region Startup File editor and locate the Minidump category in the properties window. Change the value of the Application exception property to true, and, optionally, specify the folder location where you want the minidump files to be created as the value of the Dump file location property. If the dump file location is left blank, the minidump files will be written to the folder associated with the TEMP environment variable.

When a minidump is created at run time, a message is written to both the system console and the Windows Event log indicating its name and location:

Note: If you want to be able to identify the line of source at which the exception occurred, a .pdb file for the corresponding program must be available when the minidump file is loaded into the debugger. Programs compiled for debug with the ANIM directive, or compiled for release with the ILPDB directive will have pdb files associated with them. If possible, when supplying a minidump to technical support, please include associated PDB files for your application .

Micro Focus compile all the Enterprise Server for .NET assemblies in Release mode with the ILPDB directive set, and the pdb files are shipped with the product in a zip file called EnterpriseServerDotNetPdb.zip in the binAnyCpu\SEE directory in the product install location. Please include this zip in any diagnostic collection set that includes a minidump.

Parent topic: Diagnostics


Diagnostic Collection Utility

When the Micro Focus Development team helps 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, to enable customers to gather relevant data that will help Micro Focus SupportLine and Development to progress a support incident.

The seediag utility can collect the following information:

  • Database contents on selectable databases used by the Enterprise Server for .NET system.
  • Local trace table information from running regions.
  • Machine information of machines running event monitors participating in the deployment. Information retrieved includes windows event logs, TCP connection state, and running process information.

Prerequisites

The seediag utility uses some management objects provided by SQL server. If SQL server is not installed on the machine, for example an Enterprise Server installation (not Enterprise Developer), the following SQL features from the relevant feature pack need to be installed:

  • ENU\x64\SQLSysClrTypes.msi
  • ENU\x64\SharedManagementObjects.msi

Running the seediag utility

Seediag.ps1 is a powershell script and needs to be run in a 64-bit 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

    For example: powershell -ExecutionPolicy Unrestricted -File .\seediag.ps1 <parameters>

Getting help on the command line

From a 64-bit powershell command prompt, type get-help ./seediag.ps1.

Parameters to seediag.ps1:

mode

Use to specify what should be collected for diagnostics.

The following are valid modes :

  • DB - Collect database information.
  • TRACE - Collect trace information.
  • MACHINFO - Collect event logs and system information.

The default mode is DB

outdir
Use in all modes.

outdir specifies the folder location that is used by the script to store the collected results.

It defaults to the %TEMP%/ESNETCollection location, where %TEMP% is the logged on users temporary folder location .

-outdir c:\temp\collection
usedb

Use in DB mode.

Use in TRACE mode.

Use in MACHINFO 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 databases 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.

Use in MACHINFO 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 a text file name to read the input parameters from.

The text file should contain a list of parameter names without the preceding - , and values must be separated by an =.

An 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
  • Catalog View
  • Spool View
  • Sessions View
  • Locks View
  • Cross Region Resource Locks
  • ListenerControl
  • Initiators View
  • Printers View
  • Locations View
  • Requests View
  • Program Aliases View
  • 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
  • Shared Catalog Definitions
    Manage shared catalog definitions.
  • Start/Stop Region
  • Statistics: View Statistics for a Region
  • XA Resource Definitions
    Manage XA resource definitions
  • 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.

You can change the columns displayed and their order on the screen, by selecting Edit and choosing columns.

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


Catalog View

To locate this screen

  1. In the Tree pane, under SEE Administration, select Regions, and select a JES region whose Catalog you wish to view.
  2. In the Actions pane, select Catalog.

Description

The Catalog view allows you to examine the catalog for the selected JES region.

When you select a data-set in the Catalog view:
  • You can right-click and choose to edit the data-set properties or delete it.
  • You can view non-cataloged datasets in the region by un-checking Cataloged Only at the top of the Catalog View.
  • You can allocate a new dataset by clicking the Allocate icon at the top of the Catalog view.

    Once the job is selected in the Spool panel, its associated spool output is displayed in the Output panel.

  • Selecting a Spool output record and right-clicking allows you to either Open for view, or delete the associated Spool record.
  • When viewing, the Spool output is opened and displayed in the File Viewer panel at the bottom.

Each of the Catalog, Properties and File Viewer panels can be undocked and displayed elsewhere ( e.g. on another monitor). To detach, grab the Panels top bar and drag to a new location.

To re-dock, drag the panel back onto the administration tool; it will present you with locations to dock.

To reset the panels to default locations, select View > Clock Reset Windows layout.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Spool View

To locate this screen

  1. In the Tree pane under SEE Administration, select Regions, and select a JES region whose Spool you wish to view.
  2. In the Actions pane, select Spool.

Description

The Spool view allows you to see current and past jobs in the system.

When you select a job in the Spool panel:
  • You can right-click and elect to kill, flush or release a job.
  • Once the job is selected in the Spool panel, its associated spool output is displayed in the Output panel.
  • Selecting a Spool output record and right-clicking allows you to either Open for view, or delete the associated Spool record.
  • When viewing, the Spool output is opened and displayed in the File Viewer panel at the bottom.

Each of the Spool, Output, and File Viewer panels can be undocked and displayed elsewhere (e.g. on another monitor). To detatch, grab the Panels top bar and drag to a new location.

To re-dock, drag the panel back onto the administration tool, where it will present you with locations to dock.

To reset the panels to default locations, select the View menu item and Clock reset windows layout.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Sessions View

To locate this screen

  1. In the Tree pane under SEE Administration, select Regions, and select a CICS region whose session table you want to view.
  2. In the Actions pane, select Sessions.

Description

Use this screen to view the sessions currently active in the region.

You can enable auto-refresh of this view by increasing the value of the Auto-Refresh time. You can disable auto-refresh by setting the refresh time to zero.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Locks View

To locate this screen

  1. In the Tree pane, under SEE Administration, select Regions, and select a region whose locks you want to view.
  2. In the Actions pane, select Locks.

Description

Use this screen to view the active locks held on resources in the region.

You can enable auto-refresh of this view by increasing the value of the Auto-Refresh time. You can disable auto-refresh by setting the refresh time to zero.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Cross Region Resource Locks

To locate this screen

  1. In the Tree pane under System, select .
  2. Select the SQL server instance hosting the cross region database you are interested in.

Description

Use this screen to view the active locks held on resources across multiple regions.

You can enable auto-refresh of this view by increasing the value of the Auto-Refresh time. You can disable auto-refresh by setting the refresh time to zero.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


ListenerControl

To locate this screen

  1. In the Tree pane, under SEE Administration, select System.
  2. Select Listener Control.

Description

Use this screen to control listeners that are being used by regions in a nominated SQL server.

  1. Select a SQL Server instance that is hosting the regions of interest.
  2. Select the relevant node of the listener you want to control.

    By right-clicking a protocol or node, or by clicking on the relevant icons, you can:

    • start and stop protocol channels
    • add in new protocol channels
    • delete existing protocol channels
Note: It is important to be aware that changes in this view are dynamic. That is, the operations act on the live Listener instances and are immediate. Changes in this view are not persistent across cold starts. If you want to make a permanent change to the Listener configuration, do so in the Listener configuration editor.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Initiators View

To locate this screen

  1. In the Tree pane, under SEE Administration, select Regions, and select a JES region whose initiators you wish to view.
  2. In the Actions pane, select Initiators.

Description

Use this screen to view and edit the initiators that are in the live region. You can enable and disable existing initiators by selecting or de-selecting the check box on each line. You can add or delete initiators using the Add and Delete icons after highlighting a row. You can refresh the view by clicking Refresh or increasing the auto-refresh rate from zero.

Note: It is important to be aware that changes in this view are dynamic. That is, the operations act on the live region and are immediate. Changes in this view are not persistent across cold starts. If you wish to make a permanent change to the initiator list, do so in the region start up configuration.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Printers View

To locate this screen

  1. In the Tree pane, under SEE Administration, select Regions, and select a JES region whose printers you want to view.
  2. In the Actions pane, select Printers.

Description

Use this screen to view and edit the printers that are in the live region. You can enable and disable existing printers by selecting or de-selecting the check box on each line. You can add printers using the Add icon. You can refresh the view by clicking Refresh or increasing the auto-refresh rate from zero.

Note: It is important to be aware that changes in this view are dynamic. That is, the operations act on the live region and are immediate. Changes in this view are not persistent across cold starts. If you want to make a permanent change to the printer list, do so in the region start up configuration.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Locations View

To locate this screen

  1. In the Tree pane, under SEE Administration, select Regions, and select a region whose active locations you want to view.
  2. In the Actions pane, select Locations View.

Description

Use this screen to view the active locations used by the region to search for applications, files, maps, etc.

Parent topic: Enterprise Server for .NET Context Sensitive Topics


Requests View

To locate this screen

  1. In the Tree pane, under SEE Administration, select Regions, and select a region whose request queue you want to view.
  2. In the Actions pane, select Requests.

Description

Use this screen to view active and queued rests in the region. The top view displays the Active Requests . i.e, those that are currently in execution. The views will be refreshed dynamically if you increase the auto-refresh time from zero. To disable auto-refresh, set the refresh time to zero.
Parent topic: Enterprise Server for .NET Context Sensitive Topics


Program Aliases View

To locate this screen

  1. In the Tree pane, under SEE Administration, select Regions, and select a JES region whose aliases you want to see.
  2. In the Actions pane, select Program Aliases.

Description

Use this screen to view the operating region's program aliases. The view displays the active program for aliases defined to the system. You can dynamically add entries to, or delete entries from, the list.

You can also change the alias name for a defined entry by clicking in the Alias cell of interest.

Note: It is important to note that changes made in this view will not persist across cold restarts. To make permanent changes, use the region configuration editor.
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


Shared Catalog Definitions

To locate this screen

In the Tree pane under SEE Administration, select System > Shared Catalog Definitions.

Description

Select this view to list, create, or delete shared catalog definitions.

Add server instance
Use this to define a database server instance, hosting the cross-region database, containing the shared catalog definitions you want to manage.
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


XA Resource Definitions

To locate this screen

In the Tree pane under SEE Administration, select System > XA Resource Definitions.

Description

Select this view to list, create or delete XA resource definitions.

Add server instance
Use this to define a database server instance hosting the cross-region database containing the XA resource definitions you want to manage.
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
  • Configuring a Partner JES Region
  • 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 a Database XA Resource with a CICS Region Startup File
  • To Associate an MQ 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 types are disk and database folder locations. For example:
      • c:/project/bin/debug
      • sql://(dbinst)/VSAM/?folder=FOLDER1;type=folder
      • c:/test/files
    • For Application Map Paths and Application Program Paths, valid location types are:
      • Folder Location (local disk or database folders)
      • Region Database Location
      • Cross-region Database Location
      • Custom Database Location
    Note: For VSAM files, the only valid location type is a disk or database 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 a Database XA Resource with a CICS Region Startup File

When a transaction uses a SQL database, the connection string defined in the database XA resource definition associated with the region will, by default, be used to connect to that database. A database 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 a database 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 database 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 a Database XA Resource Definition
To Create an MQ XA Resource Definition
To Associate a Database XA Resource with a SIT
To Associate a Database XA Resource with a PCT
To Associate an MQ XA Resource with a CICS Region Startup File
To Associate an MQ XA Resource with a SIT
seexadef: administer XA resource definitions
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 Group
  • To Create or Edit a Startup List
  • To Create or Edit a System Initialization Table
  • FCT Definition and File Location Overrides
  • To Associate a Database XA Resource with a SIT
  • To Associate a Database XA Resource with a PCT
  • To Associate an MQ XA Resource with a SIT
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\5.0\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.

The CICS resource types within a resource definition file are :

  • PCT - Program Control Table
    • Defines the 4 character transaction id and the program name associated with it.
  • FCT - File Control Table
    • The file control table (FCT) describes user files to CICS
  • TST - Temporary Storage Table
    • The temporary storage table (TST) is a list of generic names (or prefixes) used to identify sets of temporary storage queues.
  • PPT - Processing Program Table
    • Defines the load module characteristics to CICS.

      Each load module is defined using the DFHPPT definition, which includes the name of the load module (the PROGRAM field), and the language in which the module has been written. Examples are PL/I, Assembler, or COBOL (the PGMLANG field).

  • PLT - Program Load Table
    • A program Load table (PLT) specifies programs that you want to run during CICS startup and shutdown, and groups of programs that you want to enable and disable together.
  • DCT - Destination Control Table
    • The destination control table (DCT) contains an entry for each remote, extrapartition, intrapartition, and indirect destination.
  • TCT - Terminal Control Table
    • CICS system can communicate with terminals, sequential devices, logical units, and other systems. The TCT defines each of the devices in the configuration. Each TCT entry defines the optional and variable features of the device to CICS, and specifies the optional and variable features of CICS to be used.
  • TS Model
    • A TSMODEL specifies the properties of a set of TS queues. Individual TS queues are associated with a TSMODEL by the prefix, a character string that matches the leading characters of the queue name.
  • Term
    • Defines the characteristics of a terminal device which communicates with CICS. Terminal devices include visual display units, printers
  • TypeTerm

    • Defines a set of attributes that are common to a group of terminals.

      The resource is a logical extension of the TERMINAL resource. If you have a number of terminals with the same properties, you would define one TYPETERM with the required values, and then name that TYPETERM in each TERMINAL definition (or in the autoinstall model definition if you are using autoinstall)

  • TRANCLASS

    • Defines the characteristics of a transaction class.

      Transactions that are defined as belonging to a transaction class are subject to scheduling constraints before they are allowed to execute. If transactions belonging to an active transaction class are already running, any new transactions are queued.

  • SIT - System Initialization Table
    • Contains the initialization parameters used by the system when cold starting a CICS region.
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 Group

When you organize resource definitions into groups, you should consider keeping resources together that have something in common. For example, you might keep all resources related to an application in the same group. In some cases, CICS requires you to put certain resources in the same 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.

  • To Create a New Resource Within a Group
  • To Edit An Existing Resource Within a Group
Parent topic: Defining and Configuring Resources


To Create a New Resource Within a Group

A group needs to be defined.
To add a CICS resource definition to a group:
  1. Right-click the group of interest. A pop-up menu is displayed.
  2. Select the add new option. Another pop-up list is displayed, with the type of resource to add.
  3. Select the resource type to add to the group. A dialog is displayed, to capture the resource name and description. Enter the required information and select OK.
Parent topic: To Create or Edit a Group


To Edit An Existing Resource Within a Group

The resource must be defined.
  1. In the general view, expand the group of interest. Expand the resource type of interest. You will be presented with a list of resources grouped under the resource type you selected.
  2. Click the resource you want to change. You will be presented with a dialog to the right containing the properties for that resource.
  3. Right-click the resource for other actions. A pop up menu is displayed, which will allow you to rename, install or remove the resource.
Parent topic: To Create or Edit a Group


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.
      • Right-click the item and select edit group list.

        You will be presented with a dialog in which you can add and remove groups to the startup 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.
    • To remove a startup list, select the list to remove, right-click and select remove.
    • To copy a startup list, select the list to copy, right-click and copy. You can then paste at the top level as a new start up list.
    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 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


FCT Definition and File Location Overrides

Each FCT has three properties under the category "File Location Overrides", which affect how CICS locates the underlying data file:

  • File Name
    • If the filename override is set, CICS uses that as the filename to search for instead of using the FCT name. The filename override can also contain an extension, e.g. "ACCTFIL.DAT".
  • File Extension
    • The file extension override allows a file extension to be specified. This is useful for specifying an extension but using the FCT name as the filename.
  • Folder location
    • The folder location override affects where CICS looks for the file.

      If the folder location override is set to the absolute path of a disk or database folder, then CICS will only look for the file in that folder and does not use the data file locations.

      The folder override can also be set to a relative path (e.g. "subfolder1/subfolder2/") in which case CICS applies that relative folder to each of the data file locations to locate the file.

Previously, the "Folder" property was named "Path" and it was possible to set it to the full absolute path to the file. This is no longer possible. This field can now only contain a relative or absolute folder.

Any FCTs that made use of the Path property must be modified. For example:

FCT ( Name=fct1 Path="c:\folder\file1.dat" )

should be converted to:

FCT ( Name=fct1 FileName="file1.dat" )

with the data file location "c:\folder\" added to the region startup file.

Previously, for CICS to locate a file in the database, the Format property had to be set to RDBMS and the Path property had to be set to the name of the datastore. This is no longer necessary. Instead, you need to add the datastore folder the file is in either to the data file locations or to the FCT folder override. The RDBMS format value can still be used as a hint to tell CICS if it creates the file (e.g. through CFCR) that it should be created in the database and not on disk.

Parent topic: Defining and Configuring Resources


To Associate a Database XA Resource with a SIT

When a transaction uses a SQL database, the connection string defined in the database XA resource definition associated with the region will, by default, be used to connect to that database. A database 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 a database 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 a Database XA Resource Definition
To Create an MQ XA Resource Definition
To Associate a Database XA Resource with a CICS Region Startup File
To Associate a Database XA Resource with a PCT
To Associate an MQ XA Resource with a CICS Region Startup File
To Associate an MQ XA Resource with a SIT
seexadef: administer XA resource definitions
Related information
About XA Resources
Configuring XA resources


To Associate a Database XA Resource with a PCT

When a transaction uses a SQL database, the connection string defined in the database XA resource definition associated with the region will, by default, be used to connect to that database. A database 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 a database 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 a database 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 database 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 database 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 a Database XA Resource Definition
To Create an MQ XA Resource Definition
To Associate a Database XA Resource with a CICS Region Startup File
To Associate a Database XA Resource with a SIT
To Associate an MQ XA Resource with a CICS Region Startup File
To Associate an MQ XA Resource with a SIT
seexadef: administer XA resource definitions
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 the Fileshare Server property and set the value to the host name 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 Format property 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


Configuring a Partner JES Region

A partner JES region must be configured if you require your CICS region to access cataloged datasets, submit JCL or use spooling. This configuration identifies the listener host name and port number required to communicate with the JES region.

A single JES region may be used as a partner of multiple CICS regions, allowing datasets to be shared between all of these regions.

  • Submitting JCL from CICS
  • Subsystem Started Task Manager (SSTM)
  • To Configure a Partner JES Region
  • To Configure a Partner JES Region with SSTM
Parent topic: CICS Region Configuration


Submitting JCL from CICS

JCL can be submitted by a CICS transaction to a partner JES region via the internal reader using one of the following methods:

  1. Transient Data Queue (TDQ)

    Define a TDQ by configuring an associated DCT resource definition as the type IntReader and write your JCL, record by record, using the EXEC CICS WRITEQ TD API directed to that TDQ. Multiple jobs can be written to the queue, each delimited by a record containing /*EOF in columns 1 to 5. To ensure that your job stream does not get interleaved with another user's job stream, access to the TDQ should be serialised using the CICS ENQ and DEQ facilities.

  2. SSTM and the CICS spooling facility

    Open the spool using the EXEC CICS SPOOLOPEN USERID('INTRDR') NODE('LOCAL') API and use the SPOOLWRITE API to write your JCL statements. The SPOOLCLOSE API is used to terminate the job stream and cause the JCL to be submitted. CICS will handle the serialisation of the spool.

    To Configure a Partner JES Region with SSTM
Parent topic: Configuring a Partner JES Region


Subsystem Started Task Manager (SSTM)

Subsystem Started Task Manager (SSTM) provides JES functionality within a CICS region. The JES functionality is equivalent to that of a task started under z/OS and is required to support CICS spooling.

When SSTM is configured for a CICS region, a long-running job associated with the CICS region gets started in the partner JES region. The associated job number is reported in the CICS region's console during region start up. The job can be viewed in the partner JES region's spool view.

CICS spooling allows files to be spooled to the JES region or JCL to be submitted via its internal reader using the SPOOLOPEN, SPOOLWRITE and SPOOLCLOSE APIs. When a file is spooled, it gets associated with the long-running job in the partner JES region as a SYSOUT dataset and gets handled like any other SYSOUT dataset would be that is created during the execution of a job. When JCL is submitted via the internal reader, it gets scheduled for execution just like any other job would be that is submitted to the JES region.

SSTM requires a partner JES region to be configured with the name of a JCL file that is to be used during CICS region initialization to start the long-running job in the JES region. This JCL is expected to have a single job step, and although the program name in the PGM= statement must be syntactically correct, it does not need to exist. Any permanent datasets allocated by the JCL will have locks acquired for them according to their disposition (i.e. DISP=SHR datasets will have a shared lock, and DISP=OLD datasets will have an exclusive lock). Any DISP=OLD datasets will be unavailable to the CICS region, or any job submitted to the JES region that references them, until the CICS region is shut down.

The following JCL is used to initialise SSTM when Default SSTM JCL is selected as the SSTM JCL file in the CICS region's start up file:
//SSTM JOB 'SSTM Initialisation',CLASS=A,MSGCLASS=X
//*
//SSTMSTEP EXEC PGM=SSTMINIT
//SYSOUT   DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSPUNCH DD SYSOUT=*
//SYSIN    DD DUMMY
//
The following JCL provides an example of how SSTM could be initialised acquiring a shared lock for MYUSER.VSAM.TESTFILE:
//MYJOB JOB 'SSTM Initialisation',CLASS=A,MSGCLASS=A
//*
//STEP1 EXEC PGM=NOTEXIST
//A     DD DSN=MYUSER.VSAM.TESTFILE,DISP=SHR
//
To Configure a Partner JES Region with SSTM
Parent topic: Configuring a Partner JES Region


To Configure a Partner JES Region

You must configure a partner JES region if you need your CICS region to access cataloged datasets, submit JCL, or use spooling. To configure a partner JES region:
  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 number 1 in the diagram below. A properties window is now displayed to the right-hand side of the Results pane.
  3. Locate the JES (ES for .NET) category in the properties window and enter the JES region's listener host name and port number as the values of the ES host and ES port properties respectively. Specify a value for the ES JES type property if JCL is to be submitted from the CICS region. Specify a value for the SSTM JCL file property if CICS spooling is to be used. See number 2 in the diagram below.
  4. Choose File > Save , or click the Save icon in the toolbar to save the file. See number 3 in the diagram below.
You must cold-start the region for the changes to take effect.
Note: The partner JES region and the listener service must be started before starting the CICS region.
Parent topic: Configuring a Partner JES Region


To Configure a Partner JES Region with SSTM

A partner JES region must be configured with SSTM if you want to use CICS spooling. To configure a partner JES region with SSTM:
  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 JES (ES for .NET) category in the properties window and enter the JES region's listener host name and port number as the values of the ES host and ES port properties respectively. A value for the ES JES type property should be specified if JCL is to be submitted from the CICS region. See 2 in the diagram below.
  4. Click on the dropdown associated with the SSTM JCL file property value and select Default SSTM JCL from the list. This will result in SSTM being initialised for the region without any permanent datasets being allocated. See 3 in the diagram below.
    Note: Selecting On Disk... or In Database Datastore... will result in a dialog being displayed from which you can select the name of the JCL file to be used for SSTM initialization. Selecting None will result in SSTM not being configured for the region.

  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.
Note: The partner JES region and the listener service must be started before starting the CICS region.
Parent topic: Configuring a Partner JES Region


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

  • casfile
    Changes the information held about a file.
  • 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


casfile

The casfile command enables you to change the information held about a file.

Syntax:

casfile {/rserver-name | /mserver-name | /fserver-name} [/dfile-DD-name]
[/e{e|u|d}][/iinput-script][/loutput-log]
[/o{oi|c}][/pnew-dataset-path][/s{y|n|a}][/t{y|n}][/w{w|r}][/uuserid][/apassword][/cgroup]
[/y]

Parameters:

/rserver-name
Name of the enterprise server to connect to. Defaults to ESDEMO
Note: When calling this utility from JCL or from a WEB service (that is, when you are running the utility within a SEP) you cannot use the /r option to connect to the server. Where this is the case, you must use the /m or /f options to connect to the server.
or:
/mserver-name
Location of the Web Services and J2EE listener for the enterprise server you want to connect to. Where server-name takes the form prototype:host:WebServicePort. For example, /mtcp:localhost:9003
or:
/fserver-name
Name of the enterprise server to connect to. This differs from the /r option, in that it performs a lookup to locate the Web Service for the enterprise server. Where server-name takes the form prototype:host:port using MFCC.
/dfile-DD-name
Name of the file whose information you want to change. This is the eight-byte DD name, identical to the one held in the FCT for the file.
/e{e|u|d}
Sets the file status, where:
e
Enable; default
u
Unenable
d
Disable
/iinput-script
Name of a file containing the parameters for the file named in file-DD-name or to multiple files.
/loutput-log
Name of file to contain the results of executing the command. The default is that the results are displayed on the enterprise server console.
/o{oi|c}
Sets the open status, where:
o
Important: -oo has been deprecated. When used, a return code 4 (warning) is received.

Instead of -oo, use the -ooi (open immediate) option. If -oo is used with a region configured for VSAM shareoption use, -ooi will be forced.

oi
Open immediate.
c
Closed.
/pnew-dataset-path
Name of a new path for the file.
/s{y|n|a}
Output full file status, where:
y
Display; default
n
Suppress
a
All files
/t{y|n}
Switch the file handler trace on or off for all files, where:
y
On; default
n
Off
/w{w|r}
Set write status, where:
w
Read/write; default
r
Read-only
/uuserid
The user ID authorizing the change.
/apassword
The password for the authorizing user ID.
/cgroup
The group to be used when running casfile commands.
If you are using external security with an enterprise server, by default, a user is assigned to their default group at logon. If the permissions in this group are not sufficient for the casfile operation, use this option to specify another group.
/y
For ES.NET CICS regions, this option attempts to ensure all FCT catalog entries defined as remote resources are current.
Note: Options /r, /m, /f are alternative ways of identifying the enterprise server that you want to connect to.

Dependencies:

You must have started the enterprise server before you can issue a casfile command.

Comments:

The /s and /f options are alternatives and are mutually exclusive.

If a path or filename contains spaces, it should be enclosed in quotation marks. For example,"e:\dev server\files"

Parent topic: CICS 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
  • Job Numbers
  • Program Aliasing
  • Sharing Catalog and Spool Files Between JES Regions
  • Spooling
    Provides information about spool housekeeping, and instructions for configuring spool files, records, and archives.
  • JES Command Line Utilities
  • Using REXX
    This topic describes how to configure and run REXX EXECs under JCL
  • Micro Focus FTP Utility MFFTP
    The MFFTP Utility allows FTP batch processing from JCL on a mainframe.
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 use 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 utilize 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 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, the job classes associated with the initiator and a description of the initiator in the Initiator name, Classes and Description entry fields respectively. Select Enabled if you want the initiator to be enabled to run jobs when the region starts. If not selected, the initiator will be unavailable to run jobs until it is enabled using the seeout command-line utility or from the Initiators view of the Enterprise Server for .NET Administration UI.

    If you do not require jobs associated with this initiator to be run on a specific machine, or a network load-balanced set of machines, click OK to dismiss the dialog and move to step 7. Otherwise click the Advanced tab. See 4 in the diagram below.

    The Advanced tab is displayed.

  6. By selecting SEP node affinity you can now specify the URI of a machine, or a network load balanced set of machines, on which jobs associated with this initiator are to be run. Enter the name of the machine/ node in the Host entry field. The full URI is displayed in the URI entry field. The full URI only needs to be entered if a non-standard URI is being used in the scale-out.

    Reasons to restrict the execution of jobs to a specific machine, or set of machines, include:
    • The licenses for third-party software used by the jobs are only installed on these machines
    • The jobs require machines with more/ less processing power than the other machines in the default scale-out
    • The jobs need to be run on machines in specific geographic areas
    Click OK to dismiss the dialog and create the initiator.
  7. The new initiator is now listed under the Initiators node. See 5 in the diagram below. To modify the properties of the initiator just created, select it and change the properties in the displayed Properties window.
  8. 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 Edit a Region Startup File Associated with a JES Region
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
seeout: administer an Enterprise Server for .NET 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 seeout or casout utilities. 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 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 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, the job classes associated with the initiator and a description of the initiator in the Initiator name, Classes and Description entry fields respectively. Select Enabled if you want the initiator to be enabled to run jobs when the region starts. If not selected, the initiator will be unavailable to run jobs until it is enabled using the seeout command-line utility or from the Initiators view of the Enterprise Server for .NET Administration UI.

    If you do not require jobs associated with this initiator to be run on a specific machine, or a network load-balanced set of machines, click OK to dismiss the dialog and move to step 6. Otherwise click the Advanced tab. See 4 in the diagram below.

    The Advanced tab is displayed
  5. By selecting SEP node affinity, you can now specify the URI of a machine, or a network load balanced set of machines, on which jobs associated with this initiator are to be run. Enter the name of the machine/node in the Host entry field. The full URI is displayed in the URI entry field. The full URI only needs to be entered if a non-standard URI is being used in the scale-out.

    Reasons to restrict the execution of jobs to a specific machine, or set of machines, include:
    • The licenses for third-party software used by the jobs are only installed on these machines
    • The jobs require machines with more/less processing power than the other machines in the default scale-out
    • The jobs need to be run on machines in specific geographic areas
    Click OK to dismiss the dialog and create the initiator.
  6. 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
seeout: administer an Enterprise Server for .NET JES region
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 either the seeout or casout utilities. 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 printers 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 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, the job classes associated with the printer and a description of the printer in the Printer name, Classes and Description entry fields respectively. The browse button at the end of the Printer name entry field can be used to browse and select an installed printer as an alternative to your entering the name by hand (see 4 in the diagram below). Select Enabled if you want the printer to be enabled to print job output when the region starts. If not selected, the printer will be unavailable to print job output until it is enabled using the seeout command-line utility or from the Printers view of the Enterprise Server for .NET Administration UI.

    If you do not require output associated with this printer to be processed on a specific machine, or a network load-balanced set of machines, click OK to dismiss the dialog and move to step 7. Otherwise click the Advanced tab. See 5 in the diagram below.

    The Advanced tab is displayed.
  6. By selecting SEP node affinity you can now specify the URI of a machine, or a network load balanced set of machines, on which outputs associated with this printer are to be printed. Enter the name of the machine/node in the Host entry field. The full URI is displayed in the URI entry field. The full URI only needs to be entered if a non-standard URI is being used in the scale-out.

    Reasons to restrict the printing of outputs to a specific machine, or set of machines, include:
    • The associated physical printer may not be available to all machines
    • The outputs need to be printed from machines in specific geographic areas
    Click OK to dismiss the dialog and create the printer.
  7. The new printer is now listed under the Printers node. See 6 in the diagram below. To modify the properties of the printer just created, select it and change the properties in the displayed Properties window.
  8. Once all changes have been made, choose File > Save, or click the Save icon in the toolbar to save the file. See 7 in the diagram below.

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

Parent topic: JES Region Configuration
Related tasks
To Edit a Region Startup File Associated with a JES Region
To Create a JES Region Startup File
To Edit a Region Startup File Associated with a JES Region
Related reference
seeout: administer an Enterprise Server for .NET JES region
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 seeout or casoututilities. Normally, printers would be defined in the region startup file to ensure that they are immediately available to print job outputs 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 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 checking Enabled. 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, the job classes associated with the printer and a description of the printer in the Printer name, Classes and Description entry fields respectively. The browse button at the end of the Printer name entry field can be used to browse and select an installed printer as an alternative to you entering the name by hand (see 4 in the diagram below). Select Enabled if you want the printer to be enabled to print job output when the region starts. If not selected, the printer will be unavailable to print job output until it is enabled using the seeout command-line utility or from the Printers view of the Enterprise Server for .NET Administration UI.

    If you do not require output associated with this printer to be processed on a specific machine, or a network load-balanced set of machines, click OK to dismiss the dialog and move to step 5. Otherwise click the Advanced tab. See 5 in the diagram below.

    The Advanced tab is displayed.

  5. By selecting SEP node affinity, you can specify the URI of a machine, or a network load balanced set of machines, on which outputs associated with this printer are to be printed. Enter the name of the machine/ node in the Host entry field. The full URI is displayed in the URI entry field. The full URI only needs to be entered if a non-standard URI is being used in the scale-out.

    Reasons to restrict the printing of outputs to a specific machine, or set of machines, include:
    • The associated physical printer may not be available to all machines
    • The outputs need to be printed from machines in specific geographic areas
    Click OK to dismiss the dialog and create the printer. The newly created printer now appears in the list of printers in the Results pane. See 6 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
seeout: administer an Enterprise Server for .NET JES region
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


Job Numbers

By default, Enterprise Server for .NET JES regions support job numbers of up to 5 digits (i.e. a maximum job number of 99999). However, if your JES region requires larger job numbers, or is being migrated from a mainframe system configured for 6 digit job numbers, in Enterprise Server for .NET 3.0 and later, you can configure the region to use job numbers of up to 7 digits (i.e. a maximum job number of 9999999).

The format of the spool records for regions configured to use 5 or 7 digit job numbers is different, so if you have a scaled out system which requires the use of regions with 7 digit job numbers, you must ensure that each machine in the scale out has been upgraded to Enterprise Server for .NET 3.0 or later, or those machines will be unable to run jobs in those regions.

All regions that use a shared catalog must be configured to all use either 5 digit job numbers or 7 digit job numbers according to the shared catalog definition (i.e. when a catalog is shared, so are the associated spool records).

You use the region start-up file editor in the Enterprise Server for .NET Administration UI to define the job number range to be used by a JES region.

  • To Configure Maximum and Minimum Job Numbers
Parent topic: JES Administration
Related information
Sharing Catalog and Spool Files Between JES Regions


To Configure Maximum and Minimum Job Numbers

To define a job number range to be used by a JES region:
  1. Open the region start-up file using the Enterprise Server for .NET Administration UI's Region Startup File Editor.
  2. Select the Region node in the Results pane. See number 1 in the diagram below. A properties window is now displayed to the right-hand side of the Results pane.
  3. Locate the Job Numbers category in the properties window and select whether you want the region to use 5 or 7 digit job numbers by setting the Restrict job numbers to 5 digits property value accordingly. By default the minimum job number used by the region is 1000. When you toggle the Restrict job numbers to 5 digits value between True and False, the default maximum job number used by the region toggles between 99999 and 9999999. To override the default minimum and maximum job number values, modify the values associated with the Minimum Job Number and Maximum Job Number properties. See number 2 in the diagram below.
  4. Click File > Save , or click the Save icon on the toolbar to save the file. See number 3 in the diagram below.

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

Parent topic: Job Numbers


Program Aliasing

Enterprise Server for .NET provides support for the most commonly used IBM batch utilities. For each supported utility, Enterprise Server for .NET provides a corresponding program (an alias) that emulates the utility's functionality. The aliases used by a region are defined in the region start-up file. The Enterprise Server for .NET Administration UI is used to view these definitions. You can add additional entries to this list, or change existing entries so that your own programs are used instead of the Enterprise Server for .NET defaults.

The Enterprise Server for .NET Administration UI also provides the Program Aliases view to allow you to see what program aliases are in effect for a region in a running system. From this view, you can add, modify or delete entries, but you should do so with extreme caution as the behavior of your batch applications could be adversely affected.
Note: Changes to entries in the Program Aliases view are preserved across region warm-starts, but will be lost when the region is cold-started unless you have made the corresponding changes to the region start-up file.
  • To Configure Program Aliases in a JES Region Startup File
  • To Administer Program Aliases in a Running JES Region
Parent topic: JES Administration


To Configure Program Aliases in a JES Region Startup File

The aliases to be used by a region are defined in the region start-up file. The Enterprise Server for .NET Administration UI is used to view these definitions. You can add additional entries to this list, or change existing entries so that your own programs are used instead of the Enterprise Server for .NET defaults. To do this:
  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 Program Aliases node. See number 1 in the diagram below. A window is displayed, showing the program aliases already configured for the region.
  3. To change the name of the program aliased to a mainframe utility, double-click the alias name and enter the name of the program that you want it to be aliased to instead. See number 2 in the diagram below. For example, to change the alias for the IDCAMS utility from the default MFJAMS to MYAMS: Clicking away from the alias name in the grid will update its value.
  4. To add a new program/alias definition:
    1. Click Add Program Alias. See number 3 in the diagram below. The Define Program Alias dialog is displayed.
    2. Enter the name of the utility program that you are defining in the Program name field, and the name of the program that it is to be aliased to in the Alias name field.

    3. Click OK to dismiss the Define Program Alias dialog and complete the creation of the definition. The newly created definition will now be displayed in the Results pane. See number 4 in the diagram below.
  5. You can remove a program/alias pair that you have added by selecting the item in the grid and clicking the delete key.
    Note: System definitions cannot be deleted from a region start-up definition, so if you do not want one defined for the region, select the item in the grid and check the Omit column.
  6. Choose File > Save, or click the Save icon in the toolbar to save the file. See number 5 in the diagram below.
You must cold-start the region for the changes to take effect.
Parent topic: Program Aliasing


To Administer Program Aliases in a Running JES Region

The aliases being used by a region will have been defined in the region start-up file and created during a cold-start. The Enterprise Server for .NET Administration UI is used to view these definitions. You can add additional entries to this list, or change existing entries so that your own programs are used instead of the Enterprise Server for .NET defaults. To do this:
  1. Select a JES region from within the Enterprise Server for .NET Administration UI, and click Program Aliases in the Action pane. See 1 in the diagram below. The Program Aliases view is displayed in the Results pane.

  2. To change the name of the program aliased to a mainframe utility, double-click the alias name and enter the name of the program that you want it to be aliased to instead. See 2 in the diagram below. For example, to change the alias for the IDCAMS utility from the default MFJAMS to MYAMS:

    Clicking away from the alias name in the grid will update its value.
    Note: Modify entries with extreme caution, as doing so may result in application failure.
  3. To add a new program/alias definition:
    1. Click Add. See 3 in the diagram below.

      The Define Program Alias dialog is displayed.
    2. Enter the name of the utility program that you are defining in the Program name field, and the name of the program that it is to be aliased to in the Alias name field.

    3. Click OK to dismiss the Define Program Alias dialog and complete the creation of the definition. The newly created definition is displayed in the Results pane. See 4 in the diagram below.

  4. You can remove a program/alias pair that you have added by selecting the item in the grid and hitting the delete key.
    Note: Delete entries with extreme caution, as doing so may result in application failure
Any changes made in this view are immediately applied to the region, but only get picked up by jobs that subsequently go into execution. Jobs currently in execution are not affected by these changes. The changes will be persisted across warm-starts, but will be lost when the region is cold-started unless you have made the corresponding changes to the region start-up file.
Parent topic: Program Aliasing


Sharing Catalog and Spool Files Between JES Regions

Enterprise Server for .NET allows catalog and spool files to be shared between JES regions. This capability is typically needed when multiple regions need access to the same datasets. A job submitted to a region configured to use shared catalog and spool files will always be executed by an initiator associated with that region, irrespective of whether any other participating region has an initiator available to run it.

Sharing catalog and spool files between JES regions requires:
  1. Creating a shared catalog definition in the cross-region database that defines the location of the catalog and associated data allocation folder. The Enterprise Server for .NET Administration UI or seeout utility can be used to do this.
  2. Modifying the region start-up file of each participating region to associate it with the shared catalog definition.
  3. Cold-starting each participating region.

When a region is configured to use shared catalog and spool files, the Spool view in the Enterprise Server for .NET Administration UI will by default show just those jobs that have been submitted to that region. However, the Spool view optionally allows you to display jobs that have been submitted by all participating regions and perform the usual release, flush and kill operations on them.

Note: A released job will always be executed by an initiator associated with the region that it was originally submitted to, and not by an initiator associated with the region that it was released from.
  • To Create a Shared Catalog Definition Using seeout
  • To Create a Shared Catalog Definition Using the MMC UI
  • To Configure a JES Region to use a Shared Catalog
  • To View a Shared Spool File
Parent topic: JES Administration
Related concepts
Job Numbers


To Create a Shared Catalog Definition Using seeout

The seeout utility can be used to create a shared catalog definition in the cross-region database. To do this you must specify the name of the definition and the locations of the catalog file and data allocation folder. For example:
seeout -usedb:mydbinst -sharedcatalog:xyz -catalog:c:\SharedCatalog\catalog.dat -dataloc:c:\SharedCatalog\DATA
will create a shared catalog definition named xyz in the cross-region database on the mydbinst database server instance. The catalog file c:\SharedCatalog\catalog.dat and data allocation folder c:\SharedCatalog\DATA are associated with the definition.
Parent topic: Sharing Catalog and Spool Files Between JES Regions
Related reference
seeout: administer an Enterprise Server for .NET JES region


To Create a Shared Catalog Definition Using the MMC UI

The Enterprise Server for .NET Administration UI can be used to view, create and delete shared catalog definitions. Shared catalog definitions are persisted in the cross-region database. To create a shared catalog definition:
  1. In the Tree pane, under System, click Shared Catalog Definitions. See number 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 number 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 OK. See number 2 in the diagram below.

      The dialog is dismissed and the database server instance is listed in the Results pane. See number 1 in the diagram below.

  3. To add a new shared catalog definition:
    1. Click the name of the database server instance where your cross-region database resides, in the Tree pane under Shared Catalog Definitions. See number 1 in the diagram below. The Shared Catalog Definitions view is displayed in the Results pane.
    2. Click Add. See number 2 in the diagram below.

      The New Shared Catalog Definition dialog is displayed.
    3. Enter the name of the resource definition you are creating in the Name field, the location of the catalog file in the System Catalog field, and the location of the data allocation folder in the Data File Location field. Select whether you want the shared catalog definition to use 5 or 7 digit job numbers by checking or unchecking Restrict job numbers to 5 digits.

    4. Click OK to dismiss the New Shared Catalog Definition dialog and complete the creation of the definition. The newly created definition will now be displayed in the Results pane.

Parent topic: Sharing Catalog and Spool Files Between JES Regions


To Configure a JES Region to use a Shared Catalog

For a JES region to be able to use a shared catalog and spool file, its region start-up file needs to be modified to make the association with a shared catalog definition. To associate a shared catalog definition with a region start-up file:
  1. Open the region start-up file using the Enterprise Server for .NET Administration UI's Region Startup File Editor.
  2. Select the Region > Catalog node in the Results pane. See number 1 in the diagram below. A properties window is now displayed to the right-hand side of the Results pane.
  3. Locate the Use shared catalog property and enter the name of the shared catalog definition name that you want associated with the region as its value. See number 2 in the diagram below. Alternatively, click the ... button to right of the property value field to display the Select Shared Catalog Definition dialog, from which you can select the required definition. The values for the Data File Location and System Catalog Location properties will have been changed to <Using shared catalog>.
    Note: If the Use shared catalog value is removed, the original Data File Location and System Catalog Location property values will be reinstated.
  4. Choose File > Save , or click the Save icon in the toolbar to save the file. See number 3 in the diagram below.

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

Parent topic: Sharing Catalog and Spool Files Between JES Regions


To View a Shared Spool File

When viewing the contents of a JES region's spool file that is shared with other regions, you can view the spool records of all regions in addition to just those of the selected region. To do this:
  1. Select a JES region that has been configured to share its catalog and spool files with other regions, from the Regions > JES node of the Tree pane. See number 1 in the diagram below.
  2. Select Actions > Spool. See number 2 in the diagram below. The JES Spool view is displayed, and all spooled jobs associated with the region are displayed.
  3. Click the Show All button. See number 3 in the diagram below. The spool view now shows all spool records in the spool file and includes the Region column which contains the name of the region that created each one. The Show All button is replaced by the Show Region button. See number 4 in the diagram below.
  4. Clicking the Show Region button will toggle the view back to showing just those spool records associated with the region.
    Note: The Show All and Show Region buttons only appear in the JES Spool view when the region is using a shared spool file.
Parent topic: Sharing Catalog and Spool Files Between JES Regions


Spooling

Provides information about spool housekeeping, and instructions for configuring spool files, records, and archives.
  • Spool Housekeeping
  • Spool Record and File Contents Preservation
Parent topic: JES Administration


Spool Housekeeping

Enterprise Server for .NET provides the MVSSPLHK JCL utility program to manage the deletion and archiving of out-of-date spool files. This utility can be run directly from a JCL job, with the configuration settings held in a file or as in-stream data. This means that you do not need to recompile anything when you change any of the configuration settings.

Artifacts that are archived by MVSSPLHK include spool files, catalog files, sysout datasets and job logs. The location for writing these artefacts to can be specified in either the MVSSPLHK configuration file or region start-up file. The location is a folder under which MVSSPLHK, for each invocation, will create a sub-folder with a name indicating the date/time that the archive was created.

Region start-up file configuration is provided to allow a region to be cold-started using the spool and catalog from an archive created by MVSSPLHK.

  • To Configure a Spool HouseKeeping Archive Location
  • To Start a JES Region using a Spool Housekeeping Archive
Parent topic: Spooling
Related reference
Configuring the MVSSPLHK Housekeeping Process
Running the MVSSPLHK Housekeeping Process
Sample Parameters File


To Configure a Spool HouseKeeping Archive Location

The location MVSSPLHK, used to archive files into, can be specified in the region start-up 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 number 1 in the diagram below. A properties window is now displayed to the right-hand side of the Results pane.
  3. Locate the Spool Houskeeping category in the properties window and enter the archive location as the value of the Archive location property. See number 2 in the diagram below. Alternatively, you can click on the ... button to the right of the property value field to display the Spool Archive Location dialog, from which you can select the required location.
  4. Choose File > Save , or click the Save icon in the toolbar to save the file. See number 3 in the diagram below.

You must cold-start the region for the changes to take effect.
Parent topic: Spool Housekeeping


To Start a JES Region using a Spool Housekeeping Archive

To start a region using the spool and catalog from an archive created by MVSSPLHK, the archive location must be configured in the region start-up file. To do this:
  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 number 1 in the diagram below. A properties window is now displayed to the right-hand side of the Results pane.
  3. Locate the General category in the properties window and enter the archive location as the value of the Use spool archive property. See number 2 in the diagram below. Alternatively, click the ... button to right of the property value field to display the Spool Archive Location dialog, from which you can select the required location.
  4. Click either File > Save, or the Save icon in the toolbar to save the file. See number 3 in the diagram below.
You must cold-start the region for the changes to take effect.
Parent topic: Spool Housekeeping


Spool Record and File Contents Preservation

While started, an Enterprise Server for .NET region creates spool records and writes job information to spool files. By default, when a region is cold-started, spool records are retained and spool file contents are deleted. However, you can modify these behaviors for a specific JES region by changing the default settings for the Preserve spool records and Preserve spool file contents options in the region startup file. See To Edit a Region Startup File Associated with a JES Region for instructions.

Preserve spool records

This option specifies whether spool record files are retained or deleted when the region is cold-started.

When set to True (default), spool records are retained across cold-starts.

When set to False, a cold start automatically deletes all spool records. This is done in the background and can take some time to complete.

Restrictions:
  • Spool records can be deleted only on regions that are WAS-hosted, meaning regions started using MMC, or started using the seestart utility with the -was flag. Even when set to False, spool records are not deleted on self-hosted regions.
  • If the data file location for the region is changed before initiating a cold-start, all spool records are retained regardless of this setting.

Preserve spool file contents

This option specifies whether spool file contents are retained or deleted when the region is cold-started.

When set to True, spool records are retained across cold-starts.

When set to False (default), a cold start automatically deletes the contents of the spool file.

Restrictions:
  • This option is not available if the region uses a shared catalog/spool. In this case, the contents of the spool file cannot be deleted.
  • The spool file contains metadata that is used to populate the list of spool records displayed in the Spool View. By default, that is, when Preserve spool file contents is set to False, these spool record files are not deleted unless Preserve spool records is also set to False.
Parent topic: Spooling
Related tasks
To Edit a Region Startup File Associated with a JES Region


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
                 -sharedcatalog action options
                 -sharedcatalog:<name> 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, printer or shared catalog definition.
Used with the -initiator, - printer and -sharedcatalog commands.
-delete
Delete a shared catalog definition.
Used with the -sharedcatalog command.
-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 and shared catalog definitions.
Used with the -job, -initiator, -printer and -sharedcatalog 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

-catalog:<name>
Specify the name and location of a catalog file to be associated with a shared catalog definition.
Used with the -sharedcatalog:<name> -create action.
-class:<classes>
Job or sysout classes.
Used with the -create and -modify actions.
-dataloc:<location>
Specify the location of the data allocation folder to be associated with a shared catalog definition.
Used with the -sharedcatalog:<name> -create action.
-dd:<DD id>
List the content of the DD with the given id for a job.
Used with the -job:<jobno> -list action
-name:<printer-name>
Printer name.
Used with the -printer -create action.
-exit:<exit name>
Printer exit name.
Used with the -printer -create action.
-force
Force the deletion of a shared catalog definition.
Used with the -sharedcatalog:<name> -delete action.
-jobnodigits:<5|7>
Maximum number of job number digits. Default 5.
Used with the -sharedcatalog:<name> -create action.
-out:<output-file>
Output filename.
Used with the -job:<jobno> -list -dd<DD id> action
-password:<password>
Authorization password.
Used with all actions.
-server:<machine>[:port>]
Define the machine name and port address of JES region listener.

Default : -server:localhost:9022.

Used with -job, -initiator and -printer actions.
-step:<step-name>[:<proc-step>]
Define the step name and optional proc-step used for a job restart.
Used with the -job:<jobno> -restart action actions.
-step_info
Preserve job step information
Used with the -sharedcatalog:<name> -create action.
-usedb
Use the cross-region database on the default SQL Server instance to host the shared catalog definitions (default).
Used with the -sharedcatalog actions.
-usedb:<database-server-instance>
Use the cross-region database on the named SQL server instance to host the shared catalog definitions.
Used with the -sharedcatalog actions.
-user:<user-id>
Authorization user id.
Used with all actions.

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
  10. Create a shared catalog definition with the name MYCATALOG
    seeout -sharedcatalog:MYCATALOG -create -catalog:c:\JES\catalog.dat -dataloc:c:\JES\DATA
  11. Delete the shared catalog definition with the name MYCATALOG
    seeout -sharedcatalog:MYCATALOG -delete
  12. List all of the shared catalog definitions
    seeout -sharedcatalog -list
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


Micro Focus FTP Utility MFFTP

The MFFTP utility provides a support mechanism for batch processes that takes advantage of FTP from JCL on the mainframe. It also provides FTP support for JCL-enabled enterprise servers within Micro Focus Enterprise Server . It also provides FTP support in an Enterprise Server for .NET JES region .

The MFFTP utility is not a rewrite of an FTP client. It makes use of the platform's existing FTP client or of any third party FTP client installed on the machine.

  • Prerequisites
  • Major Features of the MFFTP Utility
  • Basic Operation
    Describes the three phases of the MFFTP utility. Reading standard FTP control cards, invoking the client and reading the output from the client.
  • Configuring the MFFTP Utility
    Details the environment variables, DD statements, input and output files, manipulation of end-of-line markers, error codes and messages.
  • Running the MFFTP Utility
  • Writing a Module to Support a Third Party FTP Client
    How to configure MFFTP to invoke a third party client.
Parent topic: JES Administration


Prerequisites

The MFFTP utility is installed as part of Micro Focus Enterprise Developer.

The MFFTP utility is installed as part of Enterprise Server for .NET

MFFTP requires:

  • An FTP client on the host system - for example, WS_FTP Pro.
  • A JCL-enabled enterprise server configured to receive JCL jobs.

Known Issues

If the FTP client connects to the FTP server using invalid credentials, and the server neither accepts anonymous access nor performs a timeout after a period of inactivity, the FTP client waits indefinitely and never returns to MFFTP. To resolve this, ensure that the correct credentials are supplied.

Parent topic: Micro Focus FTP Utility MFFTP


Major Features of the MFFTP Utility

The following features of the MFFTP utility relate to MVS datasets:

Fixed Block (FB) file support

Provides support for uploading and downloading FB files to and from the mainframe or non-mainframe servers.

The default values for MFFTP are RECFM=VB and LRECL=256, which are also the default values when uploading to the mainframe.

To upload a file to the mainframe as an FB file, use the following command to change the defaults:

QUOTE SITE RECFM=FB LRECL=XX

To download an MVS dataset as an FB file, use the LOCSITE command.

Variable Block (VB) file support

Provides support for downloading files from the mainframe or from non-mainframe servers in VB format when the control variable MFFTP_SENDEOL is set to a value other than ‘NONE’ or when the LOCSITE SBSENDEOL command is used.

If MFFTP_SENDEOL is not set (its default value is ‘NONE’) while downloading, the files are cataloged as VB but there is no file header in the physical file. Because of this, this file is not in a suitable format for uploading back to the mainframe. In such cases, the job ends with MAXCC=U00001 and you receive a message “File status of 39 (attributes mismatch)” in the console.

If MFFTP_SENDEOL is set to ‘CRLF’ while downloading VB files from the mainframe, it correctly creates a VB file with Micro Focus format-style file header and with the contents from the file on the mainframe. Similarly, in the case of non-mainframe servers, if MFFTP_SENDEOL is set to ‘CRLF’, ’CR’ or ’LF’, MFFTP correctly creates the VB file for a ‘GET’ command of a text file with ‘CRLF’, ’CR’, ’LF’ for end-of-line markers, respectively.

A VB file with an appropriate header record can be uploaded to the mainframe, either when MFFTP_SENDEOL is set to a value other than ‘NONE’ or if the LOCSITE command is used with SBSENDEOL=XX. If MFFTP_SENDEOL is not set while uploading a VB file, the ftp fails with error message “451-File transfer failed. File contains records that are longer than the LRECL of the new file.” To indicate the end-of-each record, you need to use the LOCSITE command with SBSENDEOL=CRLF or set MFFTP_SENDEOL=CRLF. If the file to be uploaded is in ASCII format, you must use the ftp command ‘ASCII’.

If SENDEOL is specified, MFFTP creates a temporary file as part of the FTP process. It is called fxxxxxxx.snnn.eol.zzzz, where xxxxxxx is the JES job number, nnn is the step number and zzzz is a sequence number. This temporary file is created by reading the file to be uploaded and copying its contents. The file is used in the transfer instead of the original physical file. For the PUT command, an end-of-line file (Line Sequential) is always created and used for the transfer of VB files, even if the SENDEOL parameter is not set.

Generation Data Group (GDG) file support

Provides support for uploading and downloading GDG files to and from the mainframe or non-mainframe servers. The GDG files can have different DCB parameters depending on the values specified by the LOCSITE and QUOTE SITE commands. If LOCSITE and QUOTE SITE are not specified, the generated files have default DCB values of RECFM=VB and LRECL=256. This is the same behavior as on the mainframe.

Parent topic: Micro Focus FTP Utility MFFTP
Related reference
MFFTP Statements
MFFTP Control Variables


Basic Operation

FTP clients in distributed environments do not understand mainframe dataset names. The primary goal of MFFTP is to provide a shell such that mainframe names are translated to distributed file system names and to interact with the catalog.

In addition, other functions are available to reformat data, such as converting text files, in Micro Focus line sequential format, to mainframe format, fixed or variable length records, as well as converting between character sets.

To achieve this, MFFTP goes through three phases:

  1. Reading standard FTP control cards to create an input file for the client.

    The cards are examined and certain ones are changed before being written to the client input file. Most notable of these are the GET and PUT statements. The local filename in these cases is a mainframe name which will be converted to a distributed file system name as would be seen in the catalog. If any errors occur, the program terminates.

  2. Invoking the client.

    MFFTP creates a command line and then invokes the command. The client receives the created input cards and executes them to produce an output.

  3. Reading the output from the client.

    MFFTP checks the output to ensure the commands executed correctly. If a command fails, MFFTP terminates with a non-zero return code or aborts. In addition, if files were fetched and need to be reformatted, MFFTP performs this at this point.

  • Differences Between FTP clients on a Mainframe and Distributed Platforms
  • MFFTP Statements
    List of commands with descriptions of action.
Parent topic: Micro Focus FTP Utility MFFTP


Differences Between FTP clients on a Mainframe and Distributed Platforms

There are many differences between the FTP client on the mainframe and those on the distributed platforms, most of these being related to the environment. For example, the distributed platform does not have access to DCB information or space allocations. The MFFTP utility uses the catalog facilities to provide both the missing links between the application requirements of attributes such as DCB and a means to translate between mainframe dataset names and the actual filenames on the distributed platform. When a request is made to FTP to GET or PUT a mainframe dataset, this has to be translated to a native filename.

You can specify default values on the mainframe in one of two ways: hard-code the values in the FTP application or use the SYSFTPD DD statement to specify them. MFFTP supports both methods.

You can make changes at execution time with a LOCSITE statement. Use a LOCSTAT command to display the relevant values and where they came from, for example - SYSFTPD, LOCSITE, an environment variable or a default value.

MFFTP scans the FTP control cards and either checks them, acts upon them, or simply passes them through. The utility expects control cards to start in column 1.

Parent topic: Basic Operation


MFFTP Statements

The following statements are checked and processed:

Command | Description
# or ; or * | Indicates a comment line.
APPEND | See PUT.
ASCII | Specifies that the transfer is in ASCII mode.
BINARY | Specifies that the transfer is in BINARY mode.
BYE | Ends the FTP session. If MFFTP does not find a BYE statement, it inserts one.
CD | Changes directory on remote machine. MFFTP performs a check that "spacey" directory names have been double quoted. If not then it will surround it in double quotes. If single quotes have been used they are replaced with double quotes.
GET

When this is executed, the local name, which would be a mainframe style name, is converted to native format.

If the file does not exist, it is cataloged with the current values as shown by LOCSTat.

If the file already exists within the catalog, the REPlace option must be used, and the existing catalog attributes will be used and the existing file overwritten.

LCD | Changes the directory on the local machine. MFFTP performs a check for "spacey" directory names in the same way that CD does.
LOCSIte

Many of the options of LOCSIte are not relevant to the Enterprise Developer

Enterprise Server for .NET

environment and are ignored.

The following options are supported:

  • BLKsize or BLOCKSize
  • LRecl
  • PRImary (space allocation)
  • RECfm
  • SECondary (space allocation)
  • SPACETYPE
  • SBSENDEOL
  • MBSENDEOL
  • SBDATACONN
  • MBDATACONN
LOCSTat | Provides a list of the current settings.
MFFTP_VARS | Lists the current settings of all MFFTP variables.
MGET

In order to obtain the list of files to be transferred and cataloged, the utility will attempt to connect to the server to produce a list of matches.

This list will be used to create a series of simple GET statements.

Note: All files are processed and cataloged with the same attributes.
MPUT | The catalog will be scanned to obtain a list of the files that match the filter criteria. A simple PUT will be created for each file that matches the criteria.
OPEN

If used, this must be the first statement.

If the OPEN statement has an IP address or host name, this will be overridden by any on the EXEC statement.

PROMPT | By default, MGET or MPUT prompts for confirmation. If no PROMPT is seen before an MGET or MPUT is encountered, one will be inserted before and after the generated simple statements.
PUT | When this is executed, MFFTP converts the local name, which would be a mainframe style name, to native format.
QUIT | Equivalent to BYE.
TYPE

The distributed platform expects ASCII or BINARY, while the mainframe allows A (ASCII) and I (BINARY).

MFFTP changes the command as appropriate for the respective platform. Using other values causes an error.

USER | MFFTP requires that you specify a user. If the keyword “USER” is not seen, it is assumed to be either the first (if no OPEN statement found) or second (if OPEN statement found) statement.
Parent topic: Basic Operation
Related concepts
Major Features of the MFFTP Utility


Configuring the MFFTP Utility

  • Specifying Control Variables
    You can set control variables from within Enterprise Server Administration or, put them into a dataset called FTP.DATA or , optionally, by specifying the ENVVAR DD statement in JCL.
  • Specifying Control Variables in Enterprise Server for .NET
    You can set control variables in the FTP.DATA dataset or, optionally, by specifying the ENVVAR DD statement in JCL.
  • MFFTP Control Variables
  • MFFTP DD Statements
    List of the DD statements required with MFFTP and their definition.
  • Input and Output Temporary Files
  • MFFTP Using SFTP As An FTP Client
    Using SFTP as an ftp client.
  • Configuring the End-of-Line Marker
    Change the end-of-line marker in the transferred files.
  • Configuring Error Codes
    How FTP client return codes relate to MFFTP error codes.
  • Configuring the Text of Messages
    Specifies how the text for the messages can be altered using sample programs as an example.
Parent topic: Micro Focus FTP Utility MFFTP


Specifying Control Variables

You set control variables for MFFTP in the JCL-enabled enterprise server from within Enterprise Server Administration as follows:

  1. Open Enterprise Server Administration.
  2. Click Edit on the row for your server.
  3. On the General page, enter the following in the Configuration Information field:
    [ES-Environment]
MFFTP_var-name=var-value
  4. Click OK.

You can create a cataloged DATASET called FTP.DATA that contains the control variables required . An example is provided in the example given in Running MFFTP.

You can use an optional ENVVAR DD statement to specify control variable values. You add this in the JCL STEP that runs MFFTP. This can be a physical dataset or instream data, as in the example given in Running MFFTP. The advantage of using this approach is that the values pertain only to the current execution and override any values set within Enterprise Server Administration.

For example - set MFFTP_KEEP to ‘N’ in the Enterprise Server Administration. When the files are required to diagnose an issue you can keep the files by adding the following DD entry in the JCL step:
//ENVVAR   DD *
MFFTP_KEEP=Y
Parent topic: Configuring the MFFTP Utility
Related reference
Running the MFFTP Utility


Specifying Control Variables in Enterprise Server for .NET

You set control variables for MFFTP in an Enterprise Server for .NET JES region as follows:

  1. Create and catalog a dataset called FTP.DATA that contains the control variables global to the region. An example is provided in the example given in Running MFFTP.

You can use an optional ENVVAR DD statement to specify control variable values. You add this in the JCL STEP that runs MFFTP. This can be a physical dataset or instream data, as in the example given in Running MFFTP. The advantage of using this approach is that the values pertain only to the current execution and override any values set within Enterprise Server Administration.

For example - set MFFTP_KEEP to ‘N’ in the Enterprise Server Administration. When the files are required to diagnose an issue you can keep the files by adding the following DD entry in the JCL step:
//ENVVAR   DD *
MFFTP_KEEP=Y
Parent topic: Configuring the MFFTP Utility


MFFTP Control Variables

You can use the following control variables to configure the MFFTP utility:

MFFTP_ABCODE=nnnn
If MFFTP has to abend, it defaults to a code of U0001. Use this variable to set a value in the range 1-4095.
MFFTP_ABEND=RC8
If MFFTP finds an error in the input stream or encounters an I/O error, the default action is to terminate with a user abend code U0001. Using this control variable instead stops the program immediately with a return code of 8.
MFFTP_CATALOG_CHARSET=xxx
By default, new datasets are cataloged with the servers character set. You can use this variable to override the character set. Acceptable values are:
  • A
  • ASC
  • ASCII
  • E
  • EBC
  • EBCDIC

If the specified character set does not match the server’s character set, you receive a warning message.

MFFTP_CHECK_221={Y | N}

When MFFTP processes a BYE or a QUIT command, the host FTP client should receive a message prefixed with 221. If no such message is received, this indicates a network or a similar failure.

If this variable is set to Y and the 221 message is not received, the return code is set to 4.

MFFTP_EXIT_EQUALS={N |Y}

By default, if MFFTP detects an error, it exits with a non-zero return code or abends with a U0001. See MFFTP_ABCODE for information about how to change the abend code.

If EXIT=nnnn is coded on the EXEC card PARM, setting this to Y causes MFFTP to return with a return code of nnnn.

MFFTP_CLIENT={FTP | USER}

Sets the FTP client to be invoked.

If this is not specified or is set to FTP, the host's default FTP client is used.

If USER is specified, you also need to specify MFFTP_USR_FTP_PGM, and point to a module that invokes an FTP client.

MFFTP_CLIENT={FTP | SFTP | USER}

Sets the FTP client to be invoked.

If this is not specified or is set to FTP, the host's default FTP client is used.

If USER is specified, you also need to specify MFFTP_USR_FTP_PGM, and point to a module that invokes an FTP client.

If SFTP is specified, the job will invoke the mffstp.cmd which drives putty ssh client.

MFFTP_EPSV={N | Y}

Some FTP servers need to be sent the EPSV command after the USER command. The default is to keep the session as active.

Setting this to Y causes the server to enter into a passive FTP session. Use this if the server uses the IPv6 communications protocol. This enables FTP connections where the user is behind routers or firewalls, where connections over an active PORT/EPRT ftp session might not work.

MFFTP_FTP_DEBUG={1 | 2}

Inserts an FTP DEBUG command into the FTP command stream.

  • A value of 1 inserts the command as the first statement.
  • A value of 2 inserts the command after the logon credentials.
MFFTP_KEEP={N | Y | C}

If set to Y, all work files are kept at the end of the step unless MFFTP_KEEP_IP=N (see below) is also set, in which case the input work file is always deleted.

If set to C, the file is deleted if the return code from the FTP client is 0; otherwise the work files are kept.

MFFTP_KEEP_IP={N | Y}
If set to N, the input work files are deleted at the end of the step, even if MFFTP_KEEP is set to Y.
MFFTP_OUTPUT_LRECL=xxx
By default, the record size (LRECL) of the OUTPUT DD statement is 133-bytes. You can use this variable to change the record size to a maximum value of 512-bytes.
MFFTP_PREFIX={N | Y}
When set to Y, causes the server instance name to be used as a prefix to the temporary filenames.
MFFTP_PROCESS_TRAILS_ONGET={TRUE | FALSE}
Determines whether trailing spaces are processed during a GET command. The default is TRUE. Set to FALSE, in conjunction with the LOCSTAT value TRAILINGBLANKS=FALSE, to ignore any trailing blank spaces.
MFFTP_RETCODE=n1,n2,n3,n4
Determines the return code (condition code) returned to JES. By default, the return codes indicate:
0
No problems encountered.
4
MFFTP received output from the host FTP client that suggested an error, for example an error message in the 5nn or 4nn series. One or more commands might have failed. The “pass” or “fail” defaults can be seen in the supplied code for the MFFTPURR module which you can modify, if necessary.
8
MFFTP did not receive any output from the host FTP client that started with a recognized message number. This usually occurs if the FTP client fails to connect to the FTP server.
16
Some other fatal error.
The above four codes represent n1, n2, n3 and n4 respectively. These may be modified so that, for example, a return code of 8 is always required (MFFTP_RETCODE=0,8,8,8).
Note: All four values must be coded.
MFFTP_SENDEOL={NONE | CR | LF | CRLF}
Specifies the end-of-line characters that are typically found on text files on distributed systems. As an enterprise server instance with Mainframe Subsystem Support (MSS) is emulating a mainframe, using GET scans for the specified characters and removes them, and using a PUT command appends the specified characters to each logical record.
MFFTP_SYSPRINT_LRECL=xxx
By default, the record size (LRECL) of the SYSPRINT DD statement is 133 bytes. You can use this variable to change the record size to a maximum value of 512 bytes.
MFFTP_TEMP_DIR=dir
Specifies an absolute directory path rather than the default data directory where MFFTP creates the temporary files. The directory must already exist and be accessible by the server instance.
Note: On UNIX, ensure that this is entered using the same case as the target directory.
MFFTP_TIME={N | C | L | B}
MFFTP makes a record of the time it starts and ends, and calculates the elapsed time. It also makes a record of the time the FTP client is running. To display these times, set this directive with the following values:
N
Default, indicates no display.
C
Console
L
Listing
B
Both console and listing
MFFTP_TRANSLATE_SAFETY={ON | OFF}
By default, when code page translation is requested (by using the TRAN option on the EXEC card), MFFTP checks that a “round trip” will not corrupt data. It does this by simulating a PUT of a 256 byte area containing x’00’ through x’ff’. It then takes the resulting output and simulates a GET with that data. If the tables are correct, the result from the GET should equal the original data. Use this variable to ignore any warnings if the data does not match.
Note: Use this variable with caution.
MFFTP_UFLAG={N | Y}
Some FTP clients need to have the -u flag set. It stops MFFTP from attempting auto-authentication during the initial connection.
MFFTP_USR_FTP_PGM=program-name
This is required if MFFTP_CLIENT is set to USER. Specifies the name of a user-supplied module that invokes the FTP client.
Note: On UNIX, ensure that this is entered using the same case as the module or MFFTP reports that it is unable to call the module.
MFFTP_VERBOSE_OUTPUT={ON | OFF}
Determines what is written to the print file. By default, MFFTP prints a lot of information, including the original input cards and any errors that were encountered with them. When set to OFF, MFFTP only prints the output from the FTP client and server.
Parent topic: Configuring the MFFTP Utility
Related concepts
Major Features of the MFFTP Utility


MFFTP DD Statements

MFFTP requires one of the following DD statements:

INPUT
For JES2. Defines the command that will be sent to the native FTP client together with the actual FTP commands.
SYSIPT
For VSE. Defines the command that will be sent to the native FTP client together with the actual FTP commands.

MFFTP will use the following DD statements, if present:

OUTPUT
Specifies the preferred destination of all output including, for example, messages from MFFTP and the ftp client.
SYSPRINT
This can be used as an alternative to OUTPUT DD statement, to define preferred output destinations.
SYSFTPD
As on the mainframe. Only the keyword values described in the LOCSITE command are supported.
NETRC
As on the mainframe. This file, or in-stream data contains some login and initialization information. It is used to hide the login details in the JCL job card.
ENVVAR
Use this to code most of the control variables, one per line. It overrides any values set at a global level by, for example, the values in the FTP.DATA dataset.
Note: This is especially useful if you need to set MFFTP_KEEP to Y to resolve a problem when the same variable is set to N at system level.
SFTPAUTH
When using the SFTP client ( ftp over ssh) this DD contains authorisation configuration. Please see the sftp topic for more details.
Note: If neither OUTPUT nor SYSPRINT is present, a SYSOUT file is dynamically allocated to show the messages as well as display them in the console.

The default record length of OUTPUT and SYSPRINT is 133 characters. This may be overwritten with the variables MFFTP_OUTPUT_LRECL and MFFTP_SYSPRINT_LRECL, respectively. These variables accept a numeric value of up to 512.

Parent topic: Configuring the MFFTP Utility


Input and Output Temporary Files

MFFTP reads the input stream and creates a control file. It then invokes the appropriate FTP program, passes the control commands to it and redirects the output to a file, which is then parsed. These input and output files are created in the default data directory and are removed at the end of the task.

The naming conventions for these temporary input and output files are:

ftp.jxxxxxxx.snnn.ip and ftp.jxxxxxxx.snnn.op

Where:

  • xxxxxxx is the JES job number where MFFTP is running
  • nnn is the step number within the job
  • ip indicates this is the input file
  • op indicates this is the output file

This mechanism enables concurrent execution of multiple instances of MFFTP. The file names of the temporary files are unique because of the use of the job number and step number.

To override the location of these temporary files, set the environment variable MFFTP_TEMP_DIR.

To use the name of the enterprise server instance as a prefix in the filenames of these files, set MFFTP_PREFIX to Y. This helps make the files unique if several enterprise server instances are sharing the same MFFTP_TEMP_DIR location.

To keep these files after the end of the task for documentation, debugging or other purposes, optionally set the environment variable MFFTP_KEEP.

Parent topic: Configuring the MFFTP Utility


MFFTP Using SFTP As An FTP Client

Secure FTP or sftp is achieved by the main MFFTP program shelling out and invoking the putty sftp implementation.

This is FTP over secure shell or ssh , not FTPS or FTP using TLS.

Prerequisites

The putty toolset needs to be installed and on the path.

More specifically, the putty sftp executable psftp.exe is required.

These utilities can be downloaded from here

If you are going to use a certificate-based authorisation, a certificate needs to be available. Please refer to the putty documentation for the process used to do this.

Configuration

The following control Variables need to be configured:

MFFTP_CLIENT=SFTP
This configures the MFFTP program to use psftp as the ftp client.
MFFTP_SFTP_AUTH=n

Used to determine the artifacts to be used for authentication as follows:

Each of the 4 variables is assigned a value as follows:

1 – userid

2 – password

4 – certificate

8 – passphrase

Add the required values together to get elements to be used for authentication as follows:

1 - user id only

2 - password only

3 - userid plus password

4 - certificate only

5 - certificate plus userid

6 - certificate plus password

7 - certificate plus userid plus password

8 - invalid (need a certificate to have a passphrase)

9 - invalid

10 - invalid

11 - invalid

12 - certificate plus passphrase

13 - certificate plus passphrase plus userid

14 - certificate plus passphrase plus password

The following DD definitions provide the ability to configure authorisation parameters

  • //SFTPAUTH DD .....

    The following parameters are valid, replacing the text within <> with correct values

    machine <machine name>
    The machine name to connect for the session
    user <username>
    The user name to log in as
    pass <password>
    keypcn <path to ppk certificate file >
    Optional, only when using certificate authentication. It is preferable to store the certificate within a catalog-controlled dataset and use it in the SFTPPPK DD described below.
    keypass <pass phrase for use with ppk certificate >
    Optional. Only when using certificate and passphrase authentication.
    hostkey <specific hostkey for machine connecting to >
    This is optional. If not provided, this hostkey must exist in the machine's host key store. Please refer to putty documentation for more information.
  • //SFTPPPK DD .... Contains the ppk certificate to be used to connect to the sftp server . This method of storing the certificate is preferable to storing it on disk somewhere.

An example JCL to configure control variables in a dataset called FTP.DATA , and place the ppk certificate in a dataset called FTP.PRIV.DATA

//SETUP02 JOB 'FTP.DATA',MSGCLASS=X,CLASS=A,MSGLEVEL=(1,1)
//*--------------------------------------------------------
//DEL     EXEC PGM=IEFBR14
//DEL1    DD DSN=FTP.DATA,SPACE=(TRK,1),DISP=(MOD,DELETE)
//DEL2    DD DSN=FTP.AUTH.DATA,SPACE=(TRK,1),DISP=(MOD,DELETE)
//DEL3    DD DSN=FTP.PRIV.DATA,SPACE=(TRK,1),DISP=(MOD,DELETE)
//*==========================================================
//*       FTP.PRIV CONFIGURATION FILE
//*==========================================================
//DEFPRIV  EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY
//SYSUT1   DD *
PuTTY-User-Key-File-2: ssh-rsa
Encryption: aes256-cbc
Comment: slesz1
Public-Lines: 6
AAAAB3NzaC1yc2EAAAABJQAAAQEAmTd1uLtTsQ6RoyTuhzr3VxFBa0zAK7p91XbQ
sa1NRh9lcVs8zeI3xOzNfW4fyTAe4YUyLCxF0dSXTChDvJtqNeNa9bXiY/noTzc8
WmnWklGzOI+JoxLGIfFvzEN/LjxkB3Tzmc5ESsLLC/xTJrvcuCw/H5Wbh377xaKH
6S4NfXCtaYxWJ3vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv0MRfH15y8DqF9bWhOP6
ywmZAmIZqJeL+0cgeGFtADiV7DSGSrMyEvKayh1OTTRpgebJ40fFaqWvPW6D5yQW
LafvaQLh+OIuMc9iAUwhoetw7VNBLekIFUvwtpS6Pdrs98f0ZQ==
Private-Lines: 14
Wo+ACSDjbOHFd3XXSaYI+meJ5wgJklTLIRjYzJe6QB3bRelm0iSdPTo+lJ8Gtn0u
7mXHsszk0hXAtkv1nWAVPYszk5tk+kY/zuT9YVRp03nwsuW/WQkofNAn5C205/sC
WfvlklaYIBe5FBVmVUYu+p4FzTJYmshZDqMRLYGougB8LLI8knlRfmJn3jgjWR3Z
yRS7XIzgBExy+NX6dyv6UA1mWHU2kV22ao7NBot9M9p2BrVh8NTyYwc4SDz238H9
JIV50m+BZkmZLhRHUokABY3DwAzDQnQHMRFLJ8rOFkPw4WfrJHyy9Do1wU5PlqJ/
SF7FSpTVlzilP7aI5mzexdrXs5WZtxJ5wDvSHTUmtcQSh2YDLxAZf4IPavHsD+eM
nJh4AsU8Pvd4Op5ONPBJY1xrCdQ0AtfrvudFWjPlLJgm8901wo7Mzokbk3ys5sR+
IVu6FWCBk9iN+0KLLPxxxxxxxxxxxVmVzUK8AtbWkBr01bFSAbHiLgnwm1M4LwJz
r1vY96CrBGEfj7wCKeaFmw7FIvc1r8n3WyYcmUfiv0WqZeuBX+yb90QwxzarQBuD
Cbn7hgXgQq6ckE2BerhpM8TRpa2xHk5t0ACrZNyOIrfyRs6E+Bk6dmseMqWJYdRb
7lqdHH6smXW/fMLMurFv0P4WX7f4IPF4OrBG3CoJ3rBCTFXa6/+RaUjaC0/RKUtu
n09m8WLdxVemHhlrg99NQmLx9JEUSr+GbiriAgj5bdppZB5Niz3YiKodZVtcH3ow
90rND6pMrKF/Fs6Zkt7Oxf8bIX3yzs7dpq9OqWU0AuyS5oMwtyMdBjmDrTBEumoF
tKtHuQxX95/TXOJasCaMNRCb1RmGo7bbzo00Xjiq0UHj/fDZuGg9E1Dm2oXYGxg8
Private-MAC: 54aba03aff3cd77f65335b92b6a72df08034462b
/*
//SYSUT2  DD DSN=FTP.PRIV.DATA,SPACE=(TRK,1),UNIT=SYSDA,
//        DCB=(RECFM=LSEQ,LRECL=80),DISP=(NEW,CATLG)
/
//*==========================================================
//*       FTP.AUTH CONFIGURATION FILE
//*==========================================================
//* keypcn d:\util\putty\keys\slesz11-3private.ppk
//DEFAUTH  EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY
//SYSUT1   DD *
machine slesz1 user fred pass password
keypass slesz1ABCDEF
hostkey 12:03:da:81:ea:49:6d:96:ed:6f:46:eb:84:27:4d:12
/*
//SYSUT2  DD DSN=FTP.AUTH.DATA,SPACE=(TRK,1),UNIT=SYSDA,
//        DCB=(LRECL=80,RECFM=FB,DSORG=PS),DISP=(NEW,CATLG)
/
//*==========================================================
//*       FTP.DATA CONFIGURATION FILE
//*==========================================================
//DEFFTP   EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY
//SYSUT1   DD *

; ---------------------------------------------------------------------
; MFFTP SETTINGS
; ---------------------------------------------------------------------

MFFTP_ABCODE 3085 ; SET DEFAULT ABEND CODE FOR MFFTP

MFFTP_OUTPUT_LRECL 120

MFFTP_PREFIX=Y
MFALLOC_LOC d:\temp\j1
;MFFTP_VERBOSE_OUTPUT ON
;MFFTP_KEEP_IP Y
;MFFTP_KEEP Y
MFFTP_CLIENT=SFTP
MFFTP_SFTP_AUTH=13
..... and so on

/*
//SYSUT2  DD DSN=FTP.DATA,SPACE=(TRK,1),UNIT=SYSDA,
//        DCB=(LRECL=80,RECFM=FB,DSORG=PS),DISP=(NEW,CATLG)
//
An example JCL to use FTP using sftp.
//MFFTP05  JOB 'MFFTP TEST',CLASS=A,MSGCLASS=A
//* sftp flavour .
//*
//* Delete files
//*
//DEL1  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
 DELETE MFI01.MFFTP.FBFILE.TOUPLD FORCE
 DELETE MFI01.FTPDATA.FBFILE FORCE
 DELETE MFI01.MFFTP.GDG FORCE
 SET MAXCC=0
/*
//*
//* Allocate GDG base
//*
//ALLOC  EXEC  PGM=IDCAMS
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  *
  DEFINE  GDG -
         (NAME(MFI01.MFFTP.GDG) -
          LIMIT(5) -
          NOEMPTY -
          SCRATCH)
/*
//*
//* Create an FB/10 dataset
//*
//STEP0 EXEC PGM=IEBGENER
//SYSPRINT  DD SYSOUT=*
//SYSIN     DD DUMMY
//SYSUT1    DD *
AAAAAAAAAA
BBBBBBBBBB
/*
//SYSUT2    DD DSN=MFI01.MFFTP.FBFILE.TOUPLD,
//             DISP=(NEW,CATLG,DELETE),
//             DCB=(RECFM=FB,LRECL=10)
//*
//* Upload an MVS dataset
//*
//STEP1 EXEC PGM=MFFTP,PARM='slesz11-3.microfocus.com'
//SYSOUT DD  SYSOUT=*
//OUTPUT DD  SYSOUT=*
//SFTPAUTH DD DSN=FTP.AUTH.DATA,DISP=(SHR)
//SFTPPPK  DD DSN=FTP.PRIV.DATA,DISP=(SHR)
//INPUT  DD *
cd MFFTP_TEST
mkdir machine_os
cd machine_os
put MFI01.MFFTP.FBFILE.TOUPLD MFFTP01.txt
quit
/*
//*
//* Download a text file to an MVS dataset (FB/10)
//*
//STEP2 EXEC PGM=MFFTP,PARM='slesz11-3.microfocus.com'
//SYSOUT DD  SYSOUT=*
//OUTPUT DD  SYSOUT=*
//SFTPAUTH DD DSN=FTP.AUTH.DATA,DISP=(SHR)
//SFTPPPK  DD DSN=FTP.PRIV.DATA,DISP=(SHR)
//INPUT DD *
cd MFFTP_TEST/machine_os
locsite recfm=fb lrecl=10
get MFFTP01.txt MFI01.FTPDATA.FBFILE (rep
MFFTP_VARS
quit
/*
//*
//* Download a text file to a new GDG bias
//*
//STEP3 EXEC PGM=MFFTP,PARM='slesz11-3.microfocus.com'
//SYSOUT DD  SYSOUT=*
//OUTPUT DD  SYSOUT=*
//SFTPAUTH DD DSN=FTP.AUTH.DATA,DISP=(SHR)
//SFTPPPK  DD DSN=FTP.PRIV.DATA,DISP=(SHR)
//INPUT DD *
cd MFFTP_TEST/machine_os
locsite recfm=fb lrecl=10
locstat
get MFFTP01.txt MFI01.MFFTP.GDG(+1)
del MFFTP01.txt
cd ..
rmdir machine_os
/*
Parent topic: Configuring the MFFTP Utility


Configuring the End-of-Line Marker

The mainframe FTP appends an end-of-line marker to each record. FTP clients on distributed platforms do not do this as they have no concept of a record.

An instruction to append this end-of-line marker can be sent to MFFTP when issuing a PUT command.

By default, no marker is added. You can set it either at the job step level using the ENVVAR DD statement or at server level using the following control variable:

MFFTP_SENDEOL=xxxx

Where xxxx equals one of the following:

NONE
Adds nothing
CRLF
Adds a carriage return and a line feed (x’0D0A’)
CR
Adds a carriage return (x'0D')
LF
Adds a line feed (x’0A’)

You can also use the LOCSITE command to set the end-of-line marker. In this case, the variable name is either SBSENDEOL or MBSENDEOL, and the supported values are NONE, CRLF, CR, or LF. For example:

LOCSITE SBSENDEOL=CRLF

The LOCSITE command overwrites any other control settings and may be varied during a session. This allows you to transfer one file with a CRLF and the next one - without it.

If you use an SBSENDEOL or an MBSENDEOL followed by a space, the variable can be placed in the SYSFTPD file.

Note: If SENDEOL is specified, the original physical file is not transferred. Instead, a copy of the file is made with the name ftp.jxxxxxxx.snnn.eol.zzzz (where xxxxxxx is the JES job number, nnn is the step number and zzzz is a sequence starting at 1 for this invocation of MFFTP). This file contains the appropriate end-of-line characters and is the file that is transferred.

By default, when MFFTP terminates, this file is deleted. To keep the file, you need to set MFFTP_KEEP to Y. If SENDEOL is set to NONE and a GET is performed for a variable record file, the results are unlikely to be as expected, as the program has no way of determining the end of each record in the fetched file.

Parent topic: Configuring the MFFTP Utility


Configuring Error Codes

Once the FTP client program executes, MFFTP scans the output looking for standard FTP responses. These take the form of 3-digit codes – for example, 331 which means the user id is correct but a password is required. Based on these codes, MFFTP sets the JCL condition code to either 0 for no errors or 4 for one or more errors.

Generally, error 332 and the codes in the 4nn and 5nn range are treated as errors.

If no messages are found, this indicates that the client was unable to connect to the server and the return code is set to 8.

If the messages which are predefined as errors do not meet your needs, you can change them using the user-configurable module, MFFTPURR. Each message is given a “pass” or “fail” rating which you can change and compile. If an MFFTPURR load module is found, its definitions will be used instead of the default ones.

Parent topic: Configuring the MFFTP Utility


Configuring the Text of Messages

The text of each message is determined by the FTP server in use rather than by MFFTP, and varies depending on the server implementation. When checking the pass or fail status of each message, another user-configurable module, MFFTPMSG, is available to alter the text of the message.

MFFTPMSG provides an example of how to replace the text of the message identified by code 230 with the simple text “User logged on”. Replacing the text in this way can be useful when you want to hide the name of the user. As with MFFTPURR, the load module is used, if located.

MFFTPMSG and MFFTPURR are sample programs shipped with the product in the src directory of the <install-dir> directory. If you want to use any of these modules, you need to compile them and put them in a location where they can be loaded by the run-time system - on the PATH defined as the ‘JES Program Path’ in the definition of the enterprise server instance.

MFFTPMSG and MFFTPURR are sample programs shipped with the product in the src directory of the <install-dir> directory. If you want to use any of these modules, you need to compile them and put them in a location where they can be loaded by the run-time system - on the application PATH defined in the JES region configuration .

Parent topic: Configuring the MFFTP Utility


Running the MFFTP Utility

The following is a sample JCL job that creates the FTP.DATA control dataset and populates it with some variables.

The file format is based on the IBM FTP.DATA format .

//SETUP01 JOB 'FTP.DATA',MSGCLASS=X,CLASS=A,MSGLEVEL=(1,1)
//*--------------------------------------------------------
//DEL     EXEC PGM=IEFBR14
//DEL1    DD DSN=FTP.DATA,SPACE=(TRK,1),DISP=(MOD,DELETE)
//*==========================================================
//*       FTP.DATA CONFIGURATION FILE
//*==========================================================
//DEFFTP   EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY
//SYSUT1   DD *

;***********************************************************************
;                                                                      *
;   Name of File:             SEZAINST(FTCDATA)                        *
;                                                                      *
;   Descriptive Name:         FTP.DATA  (for FTP Client)               *
;                                                                      *
;   SMP/E Distribution Name:  EZAFTPAC                                 *
;                                                                      *
;   Copyright:    Licensed Materials - Property of IBM                 *
;                                                                      *
;                 "Restricted Materials of IBM"                        *
;                                                                      *
;                 5694-A01                                             *
;                                                                      *
;                 Copyright IBM Corp. 1977, 2011                       *
;                                                                      *
;                 US Government Users Restricted Rights -              *
;                 Use, duplication or disclosure restricted by         *
;                 GSA ADP Schedule Contract with IBM Corp.             *
;                                                                      *
;   Status:       CSV1R13                                              *
;                                                                      *
;                                                                      *
;   This FTP.DATA file is used to specify default file and disk        *
;   parameters used by the FTP client.                                 *
;                                                                      *
;   Note: For an example of an FTP.DATA file for the FTP server,       *
;   see the FTPSDATA example.                                          *
;                                                                      *
;   Syntax Rules for the FTP.DATA Configuration File:                  *
;                                                                      *
;   (a) All characters to the right of and including a ; will be       *
;       treated as a comment.                                          *
;                                                                      *
;   (b) Blanks and <end-of-line> are used to delimit tokens.           *
;                                                                      *
;   (c) The format for each statement is:                              *
;                                                                      *
;       parameter value                                                *
;                                                                      *
;                                                                      *
;   The FTP.DATA options are grouped into the following groups in      *
;   this sample FTP client FTP.DATA configuration data set:            *
;                                                                      *
;   0.  MFFTP settings
;   1.  Basic configuration options                                    *
;   2.  Unix System Services file options                              *
;   3.  Default attributes for MVS data set creation                   *
;   4.  MVS data set transfer options                                  *
;   5.  Code page conversion options                                   *
;   6.  DB2 (SQL) interface options                                    *
;   7.  Security options                                               *
;   8.  Timers                                                         *
;   9.  Return codes                                                   *
;   10. Checkpoint / Restart options                                   *
;   11. Socks server access                                            *
;   12. Debug (trace) options                                          *
;   13. Additional advanced options                                    *
;                                                                      *
;   For options that have a pre-selected set of values, a (D) indicates*
;   the default value for the option.                                  *
;                                                                      *
;   Options that can be changed via LOCSITE subcommands are identified *
;   with an (S).                                                       *
;                                                                      *
;***********************************************************************

; ---------------------------------------------------------------------
; MFFTP SETTINGS
; ---------------------------------------------------------------------

MFFTP_ABCODE 3085 ; SET DEFAULT ABEND CODE FOR MFFTP

MFFTP_OUTPUT_LRECL 120

MFFTP_PREFIX=Y
MFFTP_VERBOSE_OUTPUT ON
MFFTP_KEEP_IP Y
MFFTP_KEEP Y

; ---------------------------------------------------------------------
;
; 1. Basic FTP client configuration options
;
; ---------------------------------------------------------------------
;SUPPRESSIGNOREWARNINGS  FALSE   ; Suppress message EZYFT47I
                                     ; while processing remaining
                                     ; statements in this FTP.DATA
                                     ; TRUE - Yes
                                     ; FALSE (D) - No. EZYFT47I is
                                     ; issued to warn of ignored
                                     ; statements
 FILETYPE          SEQ           ; (S) Client mode of operation
                                     ; SEQ = transfer data sets or
                                     ;       files (D)
                                     ; SQL = submit queries to DB2
;SEQNUMSUPPORT FALSE             ; Support sequence numbers when input
                                     ; read from //INPUT DD file
                                     ; FALSE = (D) Do not support
                                     ;         sequence numbers.
                                     ;         EZYFS33I issued if
                                     ;         sequence numbers detected

; etcetera ......
/*
//SYSUT2  DD DSN=FTP.DATA,SPACE=(TRK,1),UNIT=SYSDA,
//        DCB=(LRECL=80,RECFM=FB,DSORG=PS),DISP=(NEW,CATLG)
//

The following is a sample JCL job that executes MFFTP:

//MFFTP01  JOB 'MFFTP TEST',CLASS=A,MSGCLASS=A
//*
//* Upload an MVS dataset
//*
//STEP1 EXEC PGM=MFFTP,PARM='my.ftp.server'
//SYSOUT DD  SYSOUT=*
//OUTPUT DD  SYSOUT=*
//INPUT  DD *
anonymous/test
cd MFFTP_TEST
put MFI01.MFFTP.FBFILE.TOUPLD MFFTP01.txt
locsite recfm=fb lrecl=10
locstat
;
get +
MFFTP01.txt MFI01.FTPDATA.FBFILE (rep
MFFTP_VARS
quit
/*
//ENVVAR  DD *
MFFTP_CLIENT=FTP
MFFTP_KEEP=Y
MFFTP_TIME=L
/*
//*

When this JCL is submitted, assuming there are no errors, you should see messages in the console similar to the ones in When FTP is the Transport Client (MFFTP_CLIENT=FTP).

  • When FTP is the Transport Client (MFFTP_CLIENT=FTP)
    Example of messages output when operating with the MFFTP_CLIENT set to FTP.
  • When Using a Third Party as the Transport Client (MFFTP_CLIENT=USER)
    Output when operating with the MFFTP_CLIENT set to USER.
Parent topic: Micro Focus FTP Utility MFFTP
Related concepts
Specifying Control Variables


When FTP is the Transport Client (MFFTP_CLIENT=FTP)

When the JCL provided in Running MFFTP is submitted and there are no errors, you should see messages in the console similar to the ones below:

141211 15545316      10472 EDMFFTP  JCLCM0188I JOB01158 MFFTP01  JOB  STARTED 15:54:52
141211 15545356      10472 EDMFFTP  Micro Focus FTP Utility V3.00.09  (32 bit) Created: 26Nov2014 10:02 15:54:53
141211 15545376      10472 EDMFFTP  ftp -s:"C:\data\example\EDMFFTP\DATA\ftp01158.s001.ip" > "C:\data\example\EDMFFTP\DATA\ftp01158.s001.op" 2>&1 15:54:53
141211 15545776      10472 EDMFFTP  JCLCM0182I JOB01158 MFFTP01  JOB  ENDED   - COND CODE 0000 15:54:57

The output from this job is similar to the following:

                Micro Focus FTP Utility V3.00.09  (32 bit) Created: 26Nov2014 10

INFO..............: V3.00.09  (32 bit) Created: 26Nov2014 10:02
INFO..............: MFFTP_CLIENT set to "FTP"
INFO..............: MFFTP_TIME set to "L"
INFO..............: Using user ftp error code checking module (MFFTPURR)
INFO..............:
INFO..............: Exec parm is "my.ftp.server".
INFO..............: 1st parm "my.ftp.server" used as remote host.
WARNING...........: Other exec parm options ignored
FTP Input.........: C:\data\example\EDMFFTP\DATA\ftp01158.s001.ip
FTP Output........: C:\data\example\EDMFFTP\DATA\ftp01158.s001.op
FTP EOL temp file.: C:\data\example\EDMFFTP\DATA\ftp01158.s001.eol
FTP GET temp file.: C:\data\example\EDMFFTP\DATA\ftp01158.s001.wk1
INFO..............: SYSFTPD not found. Trying to work without it.
INFO..............: NETRC not found. Trying to work without it.
INPUT (data)......: anonymous/****
INFO..............: Assuming the above record is the userid & password.
INPUT (data)......: cd MFFTP_TEST
INPUT (data)......: put MFI01.MFFTP.FBFILE.TOUPLD MFFTP01.txt
INPUT (data)......: locsite recfm=fb lrecl=10
INPUT (data)......: locstat
LOCSTAT...........: The following options are in effect:
LOCSTAT...........:     - blksize=6233 from hard coded DEFAULTS
LOCSTAT...........:     - lrecl=10 from LOCSITE command
LOCSTAT...........:     - recfm=FB from LOCSITE command
LOCSTAT...........:     - space_units=TRK from hard coded DEFAULTS
LOCSTAT...........:     - primary_space_units=1 from hard coded DEFAULTS
LOCSTAT...........:     - secondary_space_units=1 from hard coded DEFAULTS
LOCSTAT...........:     - volume_serial=000000 from hard coded DEFAULTS
LOCSTAT...........:     - sendeol=NONE from hard coded DEFAULTS
LOCSTAT...........:     - dataconn=NONE from hard coded DEFAULTS
LOCSTAT...........:     - trailingblanks=TRUE from hard coded DEFAULTS
INPUT (comment)...: ;
INPUT (data)......: get +
INFO..............: Continuation marker found. Getting next record.
INPUT (data)......: MFFTP01.txt MFI01.FTPDATA.FBFILE (rep
WARNING...........: "MFI01.FTPDATA.FBFILE" already exists
WARNING...........:   and will be overwritten.
INPUT (data)......: MFFTP_VARS
MFFTP Variable....: MFFTP_ABCODE=(not_set)
MFFTP Variable....: MFFTP_ABEND=(not_set)
MFFTP Variable....: MFFTP_CHECK_221=(not_set)
MFFTP Variable....: MFFTP_CLIENT=FTP
MFFTP Variable....: MFFTP_DATACONN=(not_set)
MFFTP Variable....: MFFTP_DEBUG=(not_set)
MFFTP Variable....: MFFTP_ECHO_INPUT=(not_set)
MFFTP Variable....: MFFTP_EPSV=(not_set)
MFFTP Variable....: MFFTP_EXIT_EQUALS=(not_set)
MFFTP Variable....: MFFTP_KEEP=Y
MFFTP Variable....: MFFTP_KEEP_IP=(not_set)
MFFTP Variable....: MFFTP_OUTPUT_LRECL=(not_set)
MFFTP Variable....: MFFTP_PREFIX=(not_set)
MFFTP Variable....: MFFTP_RETCODE=(not_set)
MFFTP Variable....: MFFTP_SENDEOL=(not_set)
MFFTP Variable....: MFFTP_SFTP_AUTH=(not_set)
MFFTP Variable....: MFFTP_SFTP_CONNECT_TIMEOUT=(not_set)
                Micro Focus FTP Utility V3.00.09  (32 bit) Created: 26Nov2014 10

MFFTP Variable....: MFFTP_SFTP_ERRLVL=(not_set)
MFFTP Variable....: MFFTP_SFTP_IDLE_TIMEOUT=(not_set)
MFFTP Variable....: MFFTP_SYSPRINT_LRECL=(not_set)
MFFTP Variable....: MFFTP_TEMP_DIR=(not_set)
MFFTP Variable....: MFFTP_TIME=L
MFFTP Variable....: MFFTP_TRANSLATE_SAFETY=(not_set)
MFFTP Variable....: MFFTP_UFLAG=(not_set)
MFFTP Variable....: MFFTP_USRMSG=(not_set)
MFFTP Variable....: MFFTP_USR_FTP_PGM=(not_set)
MFFTP Variable....: MFFTP_VERBOSE_OUTPUT=(not_set)
MFFTP Variable....: MF_CHARSET=A
MFFTP Variable....: MFALLOC_LOC=C:\data\example\EDMFFTP\DATA
MFFTP Variable....: MFSYSCAT=C:\data\example\EDMFFTP\CATALOG.DAT
MFFTP Variable....: ES_SERVER=EDMFFTP
INPUT (data)......: quit
OUTPUT............: ftp> Connected to my.ftp.server.
OUTPUT............: open my.ftp.server
OUTPUT............: 220 Microsoft FTP Service
OUTPUT............: User (my.ftp.server:(none)):
OUTPUT............: 331 Password required for user
OUTPUT............:
OUTPUT............: 230 User logged in
OUTPUT............: ftp> cd MFFTP_TEST
OUTPUT............: 250 CWD command successful.
OUTPUT............: ftp> Local file Remote file put
OUTPUT............: C:\data\example\EDMFFTP\DATA\MFI01.MFFTP.FBFILE.TOUPLD.DAT
OUTPUT............: MFFTP01.txt
OUTPUT............: 200 PORT command successful.
OUTPUT............: 150 Opening ASCII mode data connection for MFFTP01.txt.
OUTPUT............: 226 Transfer complete.
OUTPUT............: ftp: 20 bytes sent in Seconds Kbytes/sec.
OUTPUT............: ftp> 0.350.06Local directory now C:\data\example\EDMFFTP\DAT
OUTPUT............: ftp> lcd "C:\data\example\EDMFFTP\DATA"
OUTPUT............: Remote file Local file get
OUTPUT............: MFFTP01.txt
OUTPUT............: C:\data\example\EDMFFTP\DATA\MFI01.FTPDATA.FBFILE.DAT
OUTPUT............: 200 PORT command successful.
OUTPUT............: 150 Opening ASCII mode data connection for MFFTP01.txt(20 by
OUTPUT............: 226 Transfer complete.
OUTPUT............: ftp: 20 bytes received in Seconds Kbytes/sec.
OUTPUT............: ftp> 0.0020.00bye
OUTPUT............: 221
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.ip
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.op
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.wk1
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.mget.ip
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.mget.log
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.mget.ip
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.mget.log
INFO..............: Start............15:54:53.48
INFO..............: FTP Start........15:54:53.74
INFO..............: FTP End..........15:54:57.44
INFO..............: End..............15:54:57.45
INFO..............: Elapsed run time.   3.97 seconds
INFO..............: Elapsed FTP time.   3.70 seconds
Parent topic: Running the MFFTP Utility
Related information
When Using a Third Party as the Transport Client (MFFTP_CLIENT=USER)


When Using a Third Party as the Transport Client (MFFTP_CLIENT=USER)

The precise output depends on the client being used and what is coded within the module specified by MFFTP_USR_FTP_PGM, so no example is provided. The output will be similar to that which is provided in the example when FTP is the client - see When FTP is the Transport Client (MFFTP_CLIENT=FTP) . The lines prefixed with “OUTPUT” are from the client and may be different. The others, for example “INPUT” and “INFO”, will be the same as they are generated by MFFTP.

Parent topic: Running the MFFTP Utility
Related information
When FTP is the Transport Client (MFFTP_CLIENT=FTP)


Writing a Module to Support a Third Party FTP Client

By default, MFFTP uses the host's default FTP client for transfers. To support a third party client - for example, to provide FTPS support - it must be possible to invoke the client from a standard command line. As there could be an infinite number of variations of the commands to invoke a third party client, you need a user-written module to generate and invoke them.

The following sections describe how to configure MFFTP to invoke a third party client, the parameter block that will be passed to the user module, and what is expected of it.

  • MFFTP Invoking a Third Party Client
    MFFTP environment variables required to invoke a third party FTP client.
  • The Parameter Block
    Copybook code for the parameter block that is passed to the user module.
  • MFFTP Processing the User Module
    Requirements for writing a user module.
Parent topic: Micro Focus FTP Utility MFFTP


MFFTP Invoking a Third Party Client

You need to set the following two control variables to invoke the client:
  • Configure MFFTP to use a third party program.
    MFFTP_CLIENT=USER

  • A user-written module which is specified using MFFTP_USR_FTP_PGM invokes the third party program.

    MFFTP_USR_FTP_PGM=module

    This configures MFFTP to call the specified module, that will invoke the third part client.

If MFFTP-CLIENT is set to USER, MFFTP_USR_FTP_PGM must also be set and must name a module that is accessible to the batch process. If these conditions are not met, MFFTP aborts after validating the control cards.

Parent topic: Writing a Module to Support a Third Party FTP Client
Related information
The Parameter Block
MFFTP Processing the User Module


The Parameter Block

The code below is from the copybook MFUSRPRM.CPY. It describes the parameter block that is passed to the user module. The copybook is located in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib directory. See the comments in the code for descriptions of each field:

      *===============================================================
      *   Copyright (C) 2007-2015 Micro Focus Limited.
      *   All rights reserved.
      *===============================================================

      *****************************************************************
      * Data items related to the module specified by MFFTP_USR_PGM   *
      *                                                               *
      * (tag)-usr-ftp-function-init                               *
      *   Function to be performed set as follows:                    *
      *   if (tag)-usr-ftp-function-init                          *
      *      used to cause the module to be loaded to ensure it exists*
      *   if (tag)-usr-ftp-function-call                          *
      *      normal call                                              *
      * (tag)-usr-ftp-return-code                                 *
      *   Indicate result of the call                                 *
      *   set (tag)-usr-ftp-ok true on an INIT call or if a       *
      *       normal call was deemed successful. The calling routine  *
      *       will scan the output to determine if the call to the    *
      *       FTP client was successful                               *
      *   set (tag)-usr-ftp-fail true if this module determines   *
      *       that there was a problem and that the calling module    *
      *       should not check the output                             *
      * (tag)-usr-ftp-ip-file-data.                               *
      *   Contains the length and fully qualified name of the file    *
      *   holding the normalised FTP control statements. This may be  *
      *   used directly or read to created an edited version as input *
      *   to the FTP client                                           *
      *    (tag)-usr-ftp-ip-name-len                              *
      *      actual length of the data in (tag)-usr-ftp-ip-name   *
      *    (tag)-usr-ftp-ip-name                                  *
      *      actual file name of the file holding the normalised FTP  *
      *      control statements                                       *
      * (tag)-usr-ftp-op-file-data.                               *
      *   Contains the length and fully qualified name of the file    *
      *   to hold the output from the FTP client that will be checked *
      *   (if appropriate) and printed by the calling routine. This   *
      *   may be the actual output from the FTP client or this        *
      *   routine may write an edited version here, for example to    *
      *   remove sensitive information.                               *
      *    (tag)-usr-ftp-op-name-len                              *
      *      actual length of the data in (tag)-usr-ftp-op-name   *
      *    (tag)-usr-ftp-op-name                                  *
      *      actual file name of the file to hold the output from the *
      *      FTP client (actual or edited)                            *
      * (tag)-usr-ftp-tmp-file-data.                              *
      *   Contains the length and the name of a directory that may be *
      *   used as a work are to hold temporary files.                 *
      *    (tag)-usr-ftp-tmp-name-len                             *
      *      actual length of the data in (tag)-usr-ftp-tmp-nam   *
      *    (tag)-usr-ftp-tmp-name                                 *
      *      The name of a directory that may be used to create       *
      *      temporary files, for example an edited input file or the *
      *      output from the FTP client before it is edited           *
      *****************************************************************
      *                                                               *
       01  (tag)-mfftp-usr-ftp-parm.
         05  (tag)-usr-ftp-function                pic x(1).
           88  (tag)-usr-ftp-function-init         value '0'.
           88  (tag)-usr-ftp-function-call         value '1'.
         05  (tag)-usr-ftp-return-code             pic x(1).
           88  (tag)-usr-ftp-ok                    value '0'.
           88  (tag)-usr-ftp-fail                  value '1'.
         05  (tag)-usr-ftp-msg1                    pic x(64).
         05  (tag)-usr-ftp-msg2                    pic x(64).
         05  (tag)-usr-ftp-pass-ip-data.
           10  (tag)-usr-ftp-pass-ip-fname-len     pic 9(3).
           10  (tag)-usr-ftp-pass-ip-fname         pic x(512).
         05  (tag)-usr-ftp-pass-op-data.
           10  (tag)-usr-ftp-pass-op-fname-len     pic 9(3).
           10  (tag)-usr-ftp-pass-op-fname         pic x(512).
         05  (tag)-usr-ftp-user-ip-data.
           10  (tag)-usr-ftp-user-ip-fname-len     pic 9(3).
           10  (tag)-usr-ftp-user-ip-fname         pic x(512).
         05  (tag)-usr-ftp-user-op-data.
           10  (tag)-usr-ftp-user-op-fname-len     pic 9(3).
           10  (tag)-usr-ftp-user-op-fname         pic x(512).
         05  (tag)-usr-ftp-temp-data.
           10  (tag)-usr-ftp-temp-fname-len        pic 9(3).
           10  (tag)-usr-ftp-temp-fname            pic x(512).
Parent topic: Writing a Module to Support a Third Party FTP Client
Related information
MFFTP Invoking a Third Party Client
MFFTP Processing the User Module


MFFTP Processing the User Module

The parameter block specified in the topic The Parameter Block is passed to the user module.

As a minimum, set the return code in the INIT function and return the call. This enables the user module to call MFFTP. If the user module requires any other initialization, you need to specify the required parameters at this point.

In the CALL function, the user module should do its normal processing. The module passes four unique filenames, two of which are required by MFFTP and two that might be used by this module.

While it is not a requirement to use these names, they must be unique within the Enterprise Server environment, allowing concurrent execution without locking files.

The “PASS-IP” (ftpxxxxx.snnn.ip) is a dynamically created text file which contains the control cards that MFFTP has checked and performed any reformatting on. As a minimum, the file should include the following four records:

  • Record 1: The open statement which holds the target server and potentially the port number. The format is “open”, target-server, port (if present) each separated by a space.
  • Record 2: The user id
  • Record 3: The password
  • Record 4: "bye"

The user module writes any output from the client to this file, as it is this file that MFFTP writes to the designated print file. The client could write directly to this file or to an intermediate file, and the user module can edit the output, for example, to mask any sensitive information such as the user id or the password.

Two sample modules are provided:

  • MFWSFTP. This uses the third-party client called WS_FTP Pro and shows a few examples of “editing” that can be done before actually invoking the client. It also shows how to invoke the client.
  • MFWINFTP. This uses the Windows FTP client. This is essentially the same as setting MFFTP_CLIENT=FTP.

The two sample modules can be found in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src$COBDIR/src/enterpriseserver/exit directories.

Different clients are likely to have different requirements. Micro Focus recommends that, if you wish to use this option, you either start from scratch by creating new modules or make a copy of one of the sample modules rather than modify the original files.

To access any of the control variables, you need to call MFFTP12 rather than use the DISPLAY ENVIRONMENT-NAME / ACCEPT ENVIRONMENT-VALUE method. This is because if the variable was set using the ENVVAR DD statement or configured in the FTP.DATA dataset , it does not exist within the environment space.

To retrieve any variable, call MFFTP12 as follows:

01  ws-var-name                             pic x(32).
01  ws-var-value                            pic x(256).

move "MFFTP_var-name" to ws-var-name.
call "MFFTP12" using ws-var-name
                     ws-var-value
end-call

After the call, if MFFTP locates the variable, it is in the second parameter.

If the value in the first parameter is not an MFFTP control variable, the first byte of the second parameter is set to x’FF’.

Parent topic: Writing a Module to Support a Third Party FTP Client
Related information
MFFTP Invoking a Third Party Client
The Parameter Block


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

where the options are:

-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 | Archive the events 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 must exist in the same directory as the executable.

The config file includes 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.
    • The exit program needs to be found by the seepubsub process, either via a path search by setting the exits directory on system path, or by fully qualifying it in this parameter.

      This is especially important in the case where seepubsub is run as a Windows service because Windows services do not inherit the environment that they were installed from.

  • 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 Micro Focus Batch Scheduler Integration) and applies to the native Enterprise Server product. The architecture of Enterprise Server for .NET implementation is slightly different although the main functionality is the same.

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

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

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

MFBSI environment variables

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

The variables are:

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

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

MFBSI configuration file

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

The following is an example mfbsi.cfg file:

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

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

Running seepubsub+MFBSI standalone

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

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

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

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

Running seepubsub+MFBSI as a Windows service

This is the recommended production configuration.

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

Testing MFBSI

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

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

Running mfbsijcl manually

  1. Run "mfbsijcl jcl-name". For example, if you're using the same settings as the sample MFBSI configuration file shown above, and you're submitting JCLDEMO.JCL, this would just be "mfbsijcl JCLDEMO".
  2. mfbsijcl should not exit until the job has ended and MFBSI has retrieved the job log.
  3. When it does exit, check the exit code with "echo %ERRORLEVEL%". It is 0 if the job ran successfully.
  4. Look in the MFBSI work directory for a file named JOBnumber.log. Check that it contains the JES log for the job.
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
Related concepts
Defining Program and Data Locations
Related tasks
To Configure a JES Region's Catalog Location


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
Related concepts
Windows Azure Support


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.Dispatcher/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/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\5.0\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
  • Configuring the Dispatcher Endpoint for the Monitor
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\5.0\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


Configuring the Dispatcher Endpoint for the Monitor

You can configure the dispatcher endpoint used by an event monitor in the seemonitor.exe.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.

By default, the event monitor routes all dispatcher requests to the dispatcher running on the local machine. However, when a system is scaled out it may be more appropriate to route dispatcher requests to a dispatcher, or network load balancer, running on another machine. To do this, edit the seemonitor.exe.config file and specify the following key in the <MicroFocus.SEE.Monitor>.<services> section:
<add key="Default.dispatcher" value="net.tcp://localhost/MicroFocus/SEE.Dispatcher/DispatchSession.svc"/>
where localhost should be replaced by the name of the machine running the dispatcher.
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
  • EZASOKET support
    Details the current level of support for the IBM EZASOKET functionality.
  • 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
  • POST
  • RETRIEVE
  • START
  • WAIT EVENT
  • WAITCICS
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


POST

The POST function is supported.

Operand | Support
AFTER | Full
AT | Full
HOURS (data-value) | Full
INTERVAL (data-value) | Full
MINUTES (data-value) | Full
REQID (data-value) | Full
SECONDS (data-value) | Full
SET (ptr-ref) | Full
TIME (data-value) | 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


WAIT EVENT

The WAIT EVENT function is supported.

Operand | Support
ECADDR (ptr-ref) | Full
NAME (data-value) | Full
Parent topic: Supported IntervalControl APIs


WAITCICS

The WAITCICS function is supported.

Operand | Support
ECBLIST (data-area) | Full
NAME (data-value) | Full
NOTPURGEABLE (cvda) | Recognized
NUMEVENTS (data-value) | Full
PURGEABILITY (data-value) | Recognized
PURGEABLE (cvda) | Recognized
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\5.0\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 or a group of resources.
  • 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 or a group of resources.

Syntax:

CINS group-name

CINS resource-type(resource-id) GROUP(group-name)

Parameters:

resource-type | One of FILE, PROGRAM, TDQUEUE, TERMINAL, TRANSACTION, TRANCLASS, TYPETERM, TCPIPSERVICE, URIMAP, WEBSERVICE, PIPELINE, or DOCTEMPLATE. You must supply at least the portion of the type shown in bold/underlined, and it must be 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 down to G.

Output:

Results from the transaction are written to a temporary storage (TS) queue with a name of CEBR name, where name is the current terminal or facility ID. You can browse this queue with the supplied transaction CEBR. See CEBR - Browse Temporary Storage for more information.

Examples:

CINS MCOGROUP

This command will install all resources from the group MCOGROUP.

CINS F(ACCTFIL) G(TEST)

This command 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 TRANCLASS
    Defines the attributes of a transaction class.
  • 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..
_FQPARTNRNAM(name) Identifies a fully qualified partner name for LU62 connection definitions. This field is formed of a NETWORK ID and a Partner LU name (both must be eight characters at the most) separated by a period ('.').

If the Fully Qualified Partner name in the connection is validated and installed, it will be used at run time on the APPC Allocate verb, whereas the PARTNER LU Alias is set to binary zeroes.

For example:

DEFINE CONNECTION(T88A) GROUP(MYCONNS)
NETNAME(OFLLU0AA) INSERVICE(YES) ATTACHSEC(LOCAL) PROTOCOL(APPC)
_OPERPRTY(0) _NATLANG(E) _SESSIONMAX(4) _LUALIAS(OFLLU0AA)
_PARTNRALIAS(CICSDEV1) _ALIASAPPLID(OFLLU0AA) _MODETABLE(#INTER)
_SYNCLEVEL(2) _FQPARTNRNAM(BBNET.CICSDEV1)
  • 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 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 TRANCLASS

Definition Attributes

Keyword (default values in bold) | Description
TRANClass(name) | Names the transaction class. Mandatory. name can be up to eight alphanumeric characters in length. Do not specify a transaction class name of DFHTCL00, as that name is reserved for transactions that do not belong to any particular class.
Group(groupname) | Names the group the transaction class 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 resource. 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.
Maxactive(number) | The maximum number of transactions in this transaction class that are allowed to be active. Specify a number in the range 0 to 999.
PURGETHRESH(No|number) Defines a limit to the number of transactions queuing for this transaction class. After this limit is reached, transactions are purged. Specify a threshold:
No
The queue size is unlimited.
Number
The queue size is restricted to number. Specify a size in the range 1 to 1000000.
Parent topic: CICS 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|MMSS) 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
MMSS
The length of time after which deadlock timeout ends a suspended task. The maximum value that you can specify is 6800, representing 68 minutes, zero seconds.
DUmp(No|Yes) | Indicates whether or not Mainframe Subsystem Support produces a program dump if this transaction abends.
Runaway(SYSTEM|0|Milliseconds) 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
Milliseconds
On this system, must be a value between 1000and 270000. If less than 1000 milliseconds, changes are ignored.
Note: The mainframe allows 500 milliseconds.
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


EZASOKET support

Enterprise Server for .NET currently provides core EZASOKET support and is classified as a technology preview .

This means that if you wish to use the EZASOKET support provided with Enterprise Server for .NET you should get in touch with Micro Focus SupportLine and arrange for close support which will enable Micro Focus SupportLine and development to work closely with you.

These topics do not describe the EZASOKET or EZACICAL programming interfaces themselves. For that, please refer to the appropriate IBM documentation.

The topics below detail the EZASOKET and EZACICAL entry points supported, those that are not supported, and limitations.

  • EZASOKET Introduction
  • EZASOKET - Supported API
  • EZASOKET - Standard Transactions and Programs
Parent topic: Enterprise Server for .NET Reference Information


EZASOKET Introduction

Enterprise Server for .NET provides partial EZASOKET support which is designed to emulate, as closely as possible, the IBM implementation documented in SC31-8518-01, OS/390 SecureWay Communications Server: IP CICS Sockets Guide Version 2 Release 8 (1999). It also supports some, though not all, of the features introduced in the z/OS implementation documented in SC31-8807-02, z/OS Communications Server: IP CICS Sockets Guide Version 1 Release 5 (2004).

However, there are some differences. Enterprise Server for .NET EZASOKET support makes use of the Windows .NET TCP/IP support. Owing to differences between TCP/IP implementations, there are some circumstances in which Enterprise Server for .NET EZASOKET does not behave identically to the IBM implementation.

To use the emulation, reference the MicroFocus.SEE.Comms.Public assembly in your managed project and compile. The Micro Focus emulation mimics the IBM APIs so there should be no code change required to call the supported functionality.

General Limitations

  • Does not work in an Azure deployment.
  • A listener needs to be configured as the default EZASOKET host for the region.
    • This listener will be the listener upon which the windows sockets are created and used.
    • Only one listener per region can participate as the default EZASOKET host at a time.
      • Different listeners can be configured for different regions.
    • The listener is configured by using the listener configuration editor in the UI and setting the EZ listener setting to true for the region.

  • The features not available in this release are:

    • IPv6 support
    • raw sockets
    • multicasting
    • full support for Out-Of-Band (OOB) data

    The EZACIC09 utility program (which is used with GETADDRINFO) is not included in this release.

    The CICS Domain Name System Cache is not included in this implementation.

Parent topic: EZASOKET support


EZASOKET - Supported API

The APIs and entry points in the table below are supported. If an API is not mentioned below, it is unsupported.

If an unsupported API is called, a return code of -1 and error number of 45 - IBM error "Operation not supported" is returned.

EZASOKET / EZACICSO API Name | Limitations
ACCEPT
BIND
CLOSE
CONNECT

FCNTL | New in 2.3.1
GETCLIENTID | New in 2.3.1
GETHOSTID | New in 2.3.1
GETHOSTNAME | New in 2.3.1
GETPEERNAME | New in 2.3.1
GETSOCKNAME | New in 2.3.1
GETSOCKOPT New in 2.3.1
  • SO_ACCEPTCONN
  • SO_BROADCAST
  • SO_DEBUG
  • SO_ERROR
  • SO_KEEPALIVE
  • SO_LINGER
  • SO_RCVBUF
  • SO_REUSEADDR
  • SO_SNDBUF
  • SO_TYPE
  • TCP_NODELAY

GIVESOCKET New in 2.3.1

The CLIENT parameter is ignored. That is, this version does not support restricting which tasks can take a socket.

Cross-region GIVESOCKET is not supported.

INITAPI | The IDENT and SUBTASK parameters are ignored.
IOCTL New in 2.3.1

Only the FIONBIO and FIONREAD operations are supported.

LISTEN
NTOP
PTON
READ
SEND
SENDTO | New in 2.3.1
RECV
RECVFROM
SELECT | Where a socket specified with the ESNDMSK parameter has been the subject of a GIVESOCKET, but has not yet been the subject of a TAKESOCKET, SELECT will continue to poll the socket until the TAKESOCKET occurs. In addition, SELECT cannot test sockets which are in this "given" state for normal I/O events
SETSOCKOPT Only the following operations are supported:
  • SO_DEBUG
  • SO_KEEPALIVE
  • SO_LINGER
  • SO_RCVBUF
  • SO_REUSEADDR
  • SO_SNDBUF
  • TCP_NODELAY
SHUTDOWN | New in 2.3.1
SOCKET
  • The value of the PROTO parameter passed by the caller is ignored.

    Only STREAM and datagram sockets are supported.

TAKESOCKET New in 2.3.1

Only the TASK field of the CLIENT parameter is used. Other fields are ignored.

See GIVESOCKET above for more information on the limitations of GIVESOCKET and TAKESOCKET in this release.

TERMAPI
WRITE
EZACICAL API Name
ACCEPT
BIND
CLOSE
CONNECT
INITAPI | The IDENT and SUBTASK parameters are ignored.
GETHOSTID | New in 2.3.1
GETHOSTNAME | New in 2.3.1
GETPEERNAME | New in 2.3.1
GETSOCKNAME | New in 2.3.1
GETSOCKOPT New in 2.3.1
  • SO_ACCEPTCONN
  • SO_BROADCAST
  • SO_DEBUG
  • SO_ERROR
  • SO_KEEPALIVE
  • SO_LINGER
  • SO_RCVBUF
  • SO_REUSEADDR
  • SO_SNDBUF
  • SO_TYPE
  • TCP_NODELAY
GIVESOCKET New in 2.3.1

The CLIENT parameter is ignored. That is, this version does not support restricting which tasks can take a socket.

Cross-region GIVESOCKET is not supported.

IOCTL New in 2.3.1

Only the FIONBIO and FIONREAD operations are supported.

LISTEN
READ
RECV
SELECT | Where a socket specified with the ESNDMSK parameter has been the subject of a GIVESOCKET, but has not yet been the subject of a TAKESOCKET, SELECT will continue to poll the socket until the TAKESOCKET occurs. In addition, SELECT cannot test sockets which are in this "given" state for normal I/O events
SEND
SENDTO | New in 2.3.1
SHUTDOWN | New in 2.3.1
SOCKET
  • The value of the PROTO parameter passed by the caller is ignored.

    Only STREAM and datagram sockets are supported.

TAKESOCKET New in 2.3.1

Only the TASK field of the CLIENT parameter is used. Other fields are ignored.

See GIVESOCKET above for more information on the limitations of GIVESOCKET and TAKESOCKET in this release.

SETSOCKOPT Only the following operations are supported:
  • SO_DEBUG
  • SO_KEEPALIVE
  • SO_LINGER
  • SO_RCVBUF
  • SO_REUSEADDR
  • SO_SNDBUF
  • TCP_NODELAY
WRITE
Parent topic: EZASOKET support


EZASOKET - Standard Transactions and Programs

For more information on these items, see the IBM document SC31-8807-02, z/OS Communications Server: IP CICS Sockets Guide Version 1 Release 5.

Program | Description
EZACIC04 | EBCDIC to ASCII translation program
EZACIC05 | ASCII to EBCDIC translation program
EZACIC06 | Translates bit-masks into character arrays and character arrays into bit-masks
EZACIC14 | EBCDIC to ASCII translation program using a fixed table
EZACIC15 | ASCII to EBCDIC translation program using a fixed table
Parent topic: EZASOKET support


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
  • Printing in CICS
    Explains how SCS (LU1) and 3270 data stream (LU3) printing are supported for applications running under Managed CICS.
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 convert a native project to a managed one
  • 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 convert a native project to a managed one

You can convert an existing native Mainframe Subsystem Project to a managed Mainframe Subsystem one.

  1. In Visual Studio, open the native Mainframe Subsystem Project that you want to convert.
  2. Right-click the project in Solution Explorer, and click Create Managed Mainframe Project.
  3. Specify a name and location for the new project as required, and click Next.
  4. Specify the target version of the .NET network.
  5. Specify your preferences for the configurations for the output, and click Finish.
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. We 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
Check this 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 starts, and after the build process completes.
Advanced - Generate directives file
Check this to generate a .DIR file that lists the directives used by the compiler.
Advanced - Build Events
Click this to configure commands that execute before the build process starts, and after the build process completes.

Mainframe section

Exec CICS
Check this 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.

Output

Configure the location where the build process creates the output. This is the location that you configure for components in a region's startup file.

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:
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.
Enable SQL Server Debugging
Enable this checkbox if you want to debug SQL stored procedures . You will also need to enable SQL/CLR debugging in the SQL Server Object explorer by right clicking on the SQL server instance that is hosting your database and selecting the Allow SQL/CRR debugging checkbox
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

In Enterprise Server for .NET you can debug a transaction or job step in a distributed region. A distributed region comprises one or more Enterprise Server for .NET processes running on different machines against a central SQL server.

Enterprise Server for .NET does this by starting a debug SEP on the development machine and telling the region to route the transaction or job step to the debug SEP. This routing is configured in the debug properties in the Visual Studio project.

This local SEP method is used because during any debug session of a process, when a breakpoint is encountered, the entire process halts. This would be bad if, for example, a production process was used to debug against.

This method is sometimes incorrectly referred to as "remote" debugging. Enterprise Server for .NET does not currently support true remote debugging using the Visual Studio remote debug client.

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 executable artefacts 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.
  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. If debugging a CICS transaction, attach a terminal and run your transaction. If debugging a batch region, execute the JCL that invokes the program you want to debug.
  7. In Visual Studio, use the tools available to step through your code and set and clear breakpoints as required.
  • Configuring and Running the Debugger - CICS
    The CICS WAY.
  • Configuring and Running the Debugger - Batch
    Batch Context
  • Visual Studio Managed Server Explorer
Parent topic: Developing Mainframe Managed Subsystem Applications


Configuring and Running the Debugger - CICS

  • To Configure a Project for Debugging
  • To Configure a Region for Debugging
  • To Enable Dynamic Debugging
  • To Start and Run the Debug Session
  • To Use a TN3270 Emulator To Run CICS Transaction From Visual Studio.
  • Debugging Tutorial
Parent topic: Configuring and Running the Debugger


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:
    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.
    Enable SQL Server Debugging
    Enable this checkbox if you want to debug SQL stored procedures . You will also need to enable SQL/CLR debugging in the SQL Server Object explorer by right clicking on the SQL server instance that is hosting your database and selecting the Allow SQL/CRR debugging checkbox
  5. On the right side of the screen, select the project and open the properties pane
    Database Server Instance
    The SQL server database that the region will use
    Host
    The hostname or ip address where the listener willl be running
    MFBINP Port
    The port number for the MFBINP protocol
    Region Name
    The name of the region tjat hosts the application to debug
    TN3270 Port
    The port number that the listener will respond to for the TN3270 protocol for this region
Parent topic: Configuring and Running the Debugger - CICS
Related concepts
To Configure a Region for Debugging
To Start and Run the Debug Session
Related tasks
GUID-65A3E185-B78C-4C77-966F-657A16750D97.ditamap


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.

If dynamic debugging is not configured and you run a debug session, Visual studio will offer to set dynamic debugging on your behalf .

  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 - CICS
Related concepts
To Configure a Project for Debugging
To Start and Run the Debug Session
To Enable Dynamic Debugging
Related tasks
GUID-65A3E185-B78C-4C77-966F-657A16750D97.ditamap


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.

If the region is not configured for dynamic debugging, and you start a debug session against the region, you will be prompted to allow Visual Studio to enable dynamic debugging on your behalf. The popup behaviour can be modified in the Micro Focus Enterprise Server option in the Tools/Options dialogs.

  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 - CICS
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 .
    • If the Managed region is not running, you will be prompted to allow Visual Studio to start it on your behalf.

      The popup behaviour can be modified in the Micro Focus Enterprise Server option in the Tools/Options dialogs.

  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 - CICS
Related concepts
To Configure a Project for Debugging
To Configure a Region for Debugging
Related tasks
GUID-65A3E185-B78C-4C77-966F-657A16750D97.ditamap


To Use a TN3270 Emulator To Run CICS Transaction From Visual Studio.

A working Enterprise Server for .NET CICS region.
Enterprise Developer enables you to use a TN3270 Mainframe display to connect to a region in order to run your managed CICS applications. If you are using Micro Focus Rumba installed as part of Enterprise Developer, you have the choice of running Rumba as a standalone application or as a display control embedded in Visual Studio.
  1. Choose a TN3270 display in Enterprise Developer - click Tools > Options. Enter the result of your step here (optional).
  2. Expand Micro Focus, and click TN3270 Display. Enable options as required. For more on configuring TN3270 display options, see the Enterprise Developer product help and the section Programming > Mainframe Programming > Terminal Emulation > Running Applications in a TN3270 Mainframe Display.
  3. Start your CICS-enabled region from the Enterprise Server for .NET Administration
  4. In Visual Studio, click your project in Solution Explorer. This opens the Properties window for the project, which is located under Solution Explorer. You now need to associate your project with the region on which you are running your CICS application.
  5. Type localhost in the Host field and press Enter.
  6. From the drop-down list for the Region Name field, select your CICS-enabled region.

    Specifying a region also populates the MFBINP Port and the TN3270 Port fields with the pre-configured value.

    Note : If your region is running on a remote host, you must enter the MFBINP Port number manually.

    You now need to open your TN3270 display.

  7. Right-click your project in Solution Explorer, and Enterprise Server for .NET > Mainframe TN3270 Display. This starts the TN3270 display that is specified in the IDE options.
  8. Use the TN3270 session as you normally would.
Parent topic: Configuring and Running the Debugger - CICS


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.
  • Debugging A SQL Stored Procedure .
Parent topic: Configuring and Running the Debugger - CICS


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 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 ACCT project in the solution explorer and ensure the Project Properties Pane is available. ( 1 )     Set the following fields
    Database Server Instance (2)
    Your database server instance.
    Host (3)
    The host address where the Region is running
    MFBINP port (4)
    The port number for the binp protocol
    Region Name (5)
    ESDEMO, the region in which ACCT runs.
    TN3270 port (6)
    The port on which the TN3270 listener responds for this region ( default is normally 9023)
    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.
  7. Select the Debug tab, and set the following fields:
    CICS User, Terminal, and Transaction (7)
    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.

If you start debugging from within Visual Studio, and the Dynamic Debugging is not enabled, you will be offered the opportunity to switch it on for that session.

  1. Open Enterprise Server for .NET Administration utility.
  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 Application Map Paths 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 code, scroll down to the Procedure division, and set a breakpoint on the first line: EXEC CICS HANDLE CONDITION MAPFAIL(NO-MAP)
  2. Set any other breakpoints that you would like.
  3. Press F5 to start debugging If dynamic debugging is not set in the region definition, you will be offered the opportunity to enable it . If the Region is not started, you will be asked if you wish to start it
  4. A Rumba embedded terminal window is started and connects to the configured TN3270 port

    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.
  8. If the region was self started, it will now stop.
Parent topic: Debugging Tutorial


Debugging A SQL Stored Procedure .

The CICS BANKDEMO application has a small stored procedure example built in to it .

In order to proceed with this tutorial , please perform the following steps .

  • Configure and compile the BANKDEMO CICS application as a disk hosted application(bankdemo2 project ) as described in the samples section of this document.
  • Study the debugging topics and using that knowledge , make sure you can debug and step into the bankdemo application.
    • Pay particular attention to the SQL server debugging configuration.
      • Make sure that the Enable SQL server debugging option is set
      • Make sure that the SQL server instance is configured to allow SQL/CLR debugging .
  • Start the BANKDEMO region using the managed server explorer in Visual Studio.
  • Set a breakpoint in the ZSQLTST module on the line before the EXEC SQL EXECSP statement.
  • Set a breakpoint in the ZSQLTST module on the line containing the EXEC CICS RETURN statement.
  • Open the SQL Server Object Explorer and open the dbo.CreateEmpDb stored procedure .
    • Set a breakpoint on the line containing the DROP TABLE statement.
  • Start debugging
  • Attach a terminal to the region and type bank<enter>
    • The BANK application login screen will present.
    • Push the f5 key
  • In visual studio , the application should halt on the first breakpoint in ZSQLTST.CBL .
    • Press f5 or step , the application should now continue and break in the SQL stored procedure .
    • Step through the TSQL statements
    • Step out of the SQL procedure and the application should halt on the breakpoint with the EXEC CICS RETURN.
  • At this point the tutorial is complete.
Parent topic: Debugging Tutorial


Configuring and Running the Debugger - Batch

This is the start of your concept.

  • To Configure a Project for Debugging
  • To Configure a Region for Debugging
  • To Enable Dynamic Debugging
  • To Start and Run the Debug Session
  • To Submit a JCL Job From Visual Studio
Parent topic: Configuring and Running the Debugger


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, check Compile for Debugging.
  4. On the left of the screen, select the Debug tab. Set the Active settings dropdown to JCL. Configure the screen as follows:
    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.
    Job Class
    You can restrict the debugger to debug only transactions from a specific Job Class. If you leave this field empty, the debugger debugs programs in any Job Class.
    Job Number
    You can restrict the debugger to debug only a specific Job Number. If you leave this field empty, the debugger debugs all job Numbers
    Job Name
    You can restrict the debugger to debug a program in a specific Job Name. If you leave this field empty , the debugger will debug a program in any Job Name
    Enable SQL Server Debugging
    Enable this checkbox if you want to debug SQL stored procedures . You will also need to enable SQL/CLR debugging in the SQL Server Object explorer by right clicking on the SQL server instance that is hosting your database and selecting the Allow SQL/CRR debugging checkbox
  5. On the right side of the screen, select the project and open the properties pane.
    Database Server Instance
    The SQL server database that the region will use
    Host
    The hostname or IP address where the listener willl be running
    MFBINP Port
    The port number for the MFBINP protocol
    Region Name
    The name of the region that hosts the application to debug
    TN3270 Port
    The port number that the listener will respond to for the TN3270 protocol for this region
Parent topic: Configuring and Running the Debugger - Batch


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.

If dynamic debugging is not configured and you run a debug session, Visual Studio will offer to set dynamic debugging on your behalf.

  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 the Programs items, right-click and select Add > Folder Location.
  6. Add the output folder that contains the Debug Program locations.
  7. Save the startup file, stop, then cold-start the region.
Parent topic: Configuring and Running the Debugger - Batch


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.

If the region is not configured for dynamic debugging, and you start a debug session against the region, you will be prompted to allow Visual Studio to enable dynamic debugging on your behalf. The popup behavior can be modified in the Micro Focus Enterprise Server option in the Tools/Options dialogs.

  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 - Batch


To Start and Run the Debug Session

You must have a listener configured to connect to the debug region.

  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, click Debug > Start debugging .
    • If the Managed region is not running, you will be prompted to allow Visual Studio to start it on your behalf.

      The popup behavior can be modified in the Micro Focus Enterprise Server option in the Tools/Options dialogs.

  3. Submit a JCL job containing the program you wish to execute for debug.

    In Visual Studio, the code breaks at the set breakpoint.

  4. Use the debug actions to step through the code as needed.
  5. To stop debugging, click Debug > Stop debugging from the Visual Studio menu.
Parent topic: Configuring and Running the Debugger - Batch


To Submit a JCL Job From Visual Studio

You can submit a JCL file in your managed JCL project from within Visual Studio. You must associate your project with the JCL-enabled region first.
  1. Start your JCL-enabled region from the Enterprise Server for .NET Administration , making sure the listener is started.
  2. In Visual Studio, click your project in Solution Explorer. This opens the Properties window for the project, located under Solution Explorer. You now need to associate your project with the region to which you are submitting the JCL.
  3. Type localhost in the Host field and press Enter.
  4. From the drop-down list for the Region Name field, select your JCL-enabled region

    Specifying a region automatically populates the MFBINP Port field.

    Note : If your region is running on a remote host, you must enter the MFBINP Port number manually.

    You are now ready to submit the JCL file.

  5. Right-click the JCL file in your project, and click Submit JCL
  6. Check the Output window to see the result of submitting the job
Parent topic: Configuring and Running the Debugger - Batch


Visual Studio Managed Server Explorer

The Visual Studio Server Explorer has been extended to offer simple management for regions associated with a given database instance.

To use the Server Explorer to interact with a managed region:

  1. In Server Explorer, right-click Micro Focus Managed Servers node.

  2. Click ES.NET configuration.

  3. Enter the host address for the region
  4. Enter the Database instance the region is configured to use
  5. If you are using a non standard listener configuration, enter the details.
  6. Press OK and then refresh the view.
    • Regions available will be displayed. Only regions that have registered with the database will be displayed:

    • If an expected region is not present, go to the administration tool and start the region there . Once it has been started this way once, there should be no need to do so again.
  7. Right clicking on the region of interest will present a list of options
    • Start
      • Start the selected region
    • Stop
      • Stop the selected region
    • Restart
      • Stop then start the selected region
    • Associate with project
      • Select the project to be associated with the selected region for debug purposes.
    • Show the console log
      • Shows the console log for the selected region
    • Mainframe TN3270 Display
      • Invokes the embedded Rumba TN3270 terminal emulator and connects to the TN3270 port configured in the associated project
Parent topic: Configuring and Running the Debugger


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).

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


Printing in CICS

Mainframe CICS supports two basic types of printing: 3270 data stream (also known as 3270DS or LU3 printing), and SNA Character Stream (SCS or LU1). 3270DS printing is very similar to 3270 display output, and is supported by the Enterprise Server for .NET CICS. Simply connect a 3270DS / LU3 printer session to the region using your TN3270 client software and send output to it as you would a terminal. See the documentation for your TN3270 client software for more information.

SNA Character Stream is a printer protocol that uses EBCDIC text and control codes. Control codes are one or more bytes long, and begin with a byte value that is not a printable EBCDIC character. Typically, applications generate SCS output using the CICS SEND or SEND TEXT NOEDIT macros, with a combination of normal text and hard-coded control sequences. With Enterprise Server for .NET CICS you can connect an SCS / LU1 printer session using your TN3270 client software and print to it, much as you would on the mainframe, but there are some additional considerations.

  • Printer Mode
    Selecting the type of printer supported by a printer client session.
  • SCS Control Codes in ASCII Applications
    Considerations for SCS printing from ASCII CICS applications.
Parent topic: Developing Mainframe Managed Subsystem Applications


Printer Mode

The TN3270 protocol supports both SCS (LU1) and 3270DS (LU3) printer sessions. When a client connects and requests a printer session, the type of printer is negotiated by the client and server. Most CICS applications that send output to a printer expect a specific type of printer (either SCS or 3270DS), so you must ensure your printer client connects as the correct type.

There are two main versions of TN3270: the original protocol, sometimes called "Classic TN3270", and "TN3270E" (for Enhanced). SCS printing is only supported with TN3270E. Most client software supports TN3270E but can often be configured to use Classic TN3270. If your client is using Classic TN3270, it will always be a 3270DS printer.

With TN3270E, a printer client session can request to be a 3270DS (also called LU3) printer or an SCS (also called LU1) printer, or both. Supporting both types of printing to a single client requires mainframe capabilities that Enterprise Server for .NET CICS does not currently support. If a printer client requests both types of printing, CICS will look for a TypeTerm resource definition for the requested terminal LU name. If the client doesn't request an LU name, or the requested device does not have an associated TypeTerm, or that TypeTerm's Device property does not specify "SCSPRINT" or "3790", then the printer type will be 3270DS.

To use SCS, a printer client session can either:

  • Request only SCS printing support (and not 3270DS printing). Consult the documentation for your TN3270 client software.
  • Request an LU name that is associated with an appropriate TypeTerm:
    • The LU name sent by the client (configured in your TN3270 client software) matches a Terminal resource in the installed CICS resource definitions for the region.
    • The Terminal resource has a TypeTerm property that names a TypeTerm resource that is also installed in the region.
    • The Device property of that TypeTerm has the value or . (These two values are equivalent in Enterprise Server for .NET.)
Parent topic: Printing in CICS
Related concepts
About CICS Resource Definitions


SCS Control Codes in ASCII Applications

The SNA Character Set (SCS or LU1) printer data stream is a combination of EBCDIC characters and control sequences. Controls are one or more bytes long; some are fixed-length and others are variable-length, with a length byte included in the sequence. Each control sequence begins with a control code byte.

The SCS control code byte values are not printable characters in EBCDIC. However, many of them are printable characters in ASCII, so it is impossible to distinguish them from normal text in the output stream. This is not a problem for a EBCDIC application program, since it will send the normal text as EBCDIC, but currently Enterprise Server for .NET CICS does not support EBCDIC applications.

To enable SCS printing from ASCII applications (the only type supported in this release), Enterprise Server for .NET has mapped several of the SCS control codes to non-printable ASCII values. Programs that use those codes must be changed to use the ASCII alternatives. Typically those codes appear as hard-coded hexadecimal values in a program's data or procedure division. When translating the values, it is important to understand the SCS control sequences, since only the control code value (and not the rest of the sequence for that control code) should be changed.

Example: Single-byte control sequence

The SCS LF (Line Feed) control code is a single-byte sequence: the only byte in the sequence is the LF code itself. The LF code is x'25' in EBCDIC, but in ASCII that code point is the percent symbol ("%"), so we must use a different value in ASCII applications. Enterprise Server for .NET defines SCS LF as x'0a' for ASCII programs.

For example, an application might use the LF control code this way:

01  ws-lf  PIC X VALUE X'25'.
...
PERFORM VARYING ws-idx FROM 1 BY 1 UNTIL ws-idx = ws-idx-max
    EXEC CICS SEND FROM(ws-lines(ws-idx)) LENGTH(78) END-EXEC
    EXEC CICS SEND FROM(ws-lf) LENGTH(1) END-EXEC
END-PERFORM

This code fragment sends a series of lines of output to the printer, with LF codes after each line. In this case, you would identify the use of the x'25' control code in the definition of the ws-lf item and change it to x'0a'.

Example: Variable-length control sequence

SCS uses the TRN (Transparent) control code to send data verbatim to the printer. Applications often use TRN to send printer escape sequences to control printer functions such as font selection and page setup. In SCS the TRN control code is followed by a length byte and a variable number of data bytes. When translating SCS control sequences for ASCII programs, it's important to translate only the control code and not any of the bytes in the rest of the sequence.

The TRN code value is x'35', which is the ASCII "5" character, so for ASCII programs it must be replaced with x'03'. But the length byte N that follows it must be left unchanged, as must the next N bytes.

For example, an application might have a hard-coded printer control sequence in working storage like this:

03  FILLER   PIC X(6)  VALUE   X'35041B283855'.
03  FILLER   PIC X(7)  VALUE   X'35051B28733050'.

Those two data items each define an SCS TRN sequence. The first has the control code, a length byte indicating the sequence has 4 more bytes, and the 4 bytes of data. The second is similar but has 5 bytes of data. Here the two sequences are easy to identify because the programmer has made them separate values. However, they could have been entered as a single data item:

03  FILLER   PIC X(6)  VALUE   X'35041B28385535051B28733050'.

(The x'35' TRN codes have been bolded to show the two control sequences.)

In either case, the two TRN code bytes need to be changed to x'03', but if x'35' happened to appear within the data for either sequence, it would not be changed. So the second example would become:

03  FILLER   PIC X(6)  VALUE   X'03041B28385503051B28733050'.

This is a case where it is necessary to understand the SCS code sequences in order to translate them correctly.

  • SCS Control Code Translation
Parent topic: Printing in CICS


SCS Control Code Translation

SCS control codes that must be translated for ASCII applications, with their official name, value in EBCDIC applications, and ASCII value.

Table 1. SCS ASCII control codes
SCS control code point | SCS control name | ASCII applications should use
x'23' | WUS (Word Underscore) | x'01'
x'24' | IMP (Inhibit Presentation) | x'02'
x'25' | LF (Line Feed) | x'0a'
x'2b' | SHF/SVF/SLD (Set Horizontal/Vertical Format; Set Line Density) | x'1b'
x'2f' | BEL (Ring Bell) | x'07'
x'33' | IR (Index Return) | x'10'
x'34' | PP (Presentation Position) | x'11'
x'35' | TRN (Transparent) | x'03'
x'36' | EBS/NBS (Expanded / Numeric Backspace) | x'12'
x'38' | SBS (Subscript) | x'13'
x'39' | IT (Indent Tab) | x'17'
x'3a' | RFF/RPE (Required Form Feed / Page End) | x'18'
x'41' | RSP (Required Space) | x'19'

Note that code point x'03' is also defined in SCS as ATRN, ASCII Transparent. We use it as the ASCII alias for TRN (x'35'), so x'03' in SCS output is always translated to x'35'.

Parent topic: SCS Control Codes in ASCII Applications


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 File Storage 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 5.0


Introduction

This document outlines current support for the Windows Azure Platform (http://msdn.microsoft.com/en-us/library/dd163896.aspx) for Enterprise Developer - Enterprise Server for .NET.

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 https://azure.microsoft.com/en-gb/free/search/?&WT.srch=1&WT.

Note: If you are seriously considering using the Enterprise Server for .NET Azure deployment capability, please contact your Micro Focus representative or Micro Focus Customer Care, so we can help you with the process.
Parent topic: Windows Azure Support


What is Windows Azure?

From the Microsoft document “What is Windows Azure?” (no longer available; see https://docs.microsoft.com/en-us/azure/index for similar information):

"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 instance 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

Enterprise Server for .NET can be hosted in Windows Azure using virtual machines running Windows Server and SQL Server, in an Infrastructure as a Service (IaaS) deployment. It can also be deployed to Windows Azure as a set of distinct worker roles with SQL Azure, which is a Platform as a Service (PaaS) deployment.

IaaS has the advantage of providing the same environment as an on-premises installation of Enterprise Server for .NET. PaaS may provide easier scalability with less overhead, since worker roles are simpler than full OS installations, and better integration with other Azure features.

In earlier versions of Enterprise Server for .NET, Micro Focus recommended the PaaS deployment approach. At this time, Micro Focus does not recommend either type of deployment over the other. Customers should determine which better fits their needs.

Note:

It is not currently possible to perform dynamic debugging in an Azure PaaS deployment. Debugging is limited to CTF tracing and event logs. The recommended practice is to deploy and debug to an on-premises Enterprise Server for .NET and debug there. Only deploy production-ready applications to Azure.

Use the Enterprise Server for .NET Azure deployment and configuration wizard in the Enterprise Server for .NET Administration console system to deploy to Windows Azure.

Note:

The success of any Enterprise Server for .NET deployment into Azure relies on an on-premises deployment having been done successfully. Having an on-premises deployment to work with also gives an on-premises test system for the deployed production system. If a system works in the on-premises test system, it is more than likely to work in Azure.

Worker roles in an Azure PaaS deployment

This section briefly describes the Azure worker roles in Enterprise Server for .NET.

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, batch job submission, and other inbound communication, and can provide IBM MQ triggering.
  • Dispatcher - The worker role MicroFocus.SEE.Dispatch.Azure queues and dispatches CICS transaction requests, batch job submissions, and other work entering the Enterprise Server for .NET system.
  • SEP - The worker role MicroFocus.SEE.SEP.Azure executes application programs and provides the emulated CICS and batch environments.
  • Event monitor - The worker role MicroFocus.SEE.Monitor.Azure provides an interface for remote administration (starting/stopping regions, querying SEP statuses, etc), performs various infrastructure services, and monitors the health of the system.

See the Enterprise Server for .NET product documentation for details about each of these components.

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 https://azure.microsoft.com/en-gb/free/ for details on setting up an Azure Platform account.
  • SQL Azure server (for PaaS only). See Getting Started with SQL Azure Database using the Windows Azure Management Portal at https://docs.microsoft.com/en-us/azure/sql-database/sql-database-get-started-portal for details on setting up and accessing SQL Azure databases.
  • Azure storage account (for PaaS only). See https://docs.microsoft.com/en-us/azure/storage/ for details on how to set up an Azure storage account. You need to create a version one (Classic) storage account.
  • Windows Azure support for Visual Studio. This software is known by various names, such as Windows Azure Tools, Windows Azure SDK, or Azure Development Workload. This SDK is required on any system that deploys Enterprise Server for .NET roles to Azure.
    • For Visual Studio 2017, use the Visual Studio Installer to add the Azure Development workload to Visual Studio.
    • For earlier versions of Visual Studio, download the Azure SDK from Microsoft. At the time of writing, they can be found at https://azure.microsoft.com/en-us/downloads/. To avoid the complexity of deciding what bits to install, Micro Focus recommends using the “one click install” link, if one is available.
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 and Azure SDK version you want to give this deployment (see 1 and 2 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 3 above).

    1. The configuration files and generated files that are produced by this process are stored in the %public%\Documents\Micro Focus\Enterprise Developer\Azure folder. In the example above, the configuration file mycics.config is created in the %public%\Documents\Micro Focus\Enterprise Developer\Azure\ folder. The generated contents of a deployment are stored in a folder below that, called public%\Documents\Micro Focus\Enterprise Developer\Azure\mycics.
  4. Click Next to continue.

    The next panel configures the management certificate.

  5. Click Generate (1 above).

    A browser window opens, which takes you to the Azure portal to generate and download the certificate.

    Once you have downloaded a certificate, import it by clicking Import (2 above) and navigating to the stored certificate and selecting it. When the certificate has been imported, you are 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 are presented with the available regions for your deployment.

    Micro Focus recommends deploying to the same location as your database. If you choose a different location, that could result in significant additional latency in Enterprise Server for .NET processing.

  8. Click Next to continue.

  9. Enter the database instance ID of the SQL Azure server you want to use for the deployment (1 above). This is the ID 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 first.
  10. Enter the user ID associated with the SQL server (3 above). This will have been set 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 and 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 (5 above). 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 is inserted.

  24. Enter the Region Name and select the Region Type from the drop-down list (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 an 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 Advanced 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 item.

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). It may take some time to reach this state. If the deployment is not in this state, it will not be possible to start or use a region . Each role will go through two initializing or updating steps .
  • 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
  • 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. If you have not already done so, deploy your region startup file to the cross-region database for your Azure deployment. See Adding Configuration Files to the Cross-Region Database. In the following example, we will use the region name ESDEMO and the region startup file name region_esdemo.config.
  2. From the Windows Start menu, click the Micro Focus Enterprise Developer > Configuration > Enterprise Server for .NET Admin option to open the Microsoft Management Console (MMC).
  3. 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.

  4. In the Database server instance field of the Define Region dialog box, type the name of your SQL Azure database instance. Click Next.

  5. In the Region name field of the Define Region dialog box, type ESDEMO. Click Next.

  6. Click the Cross-region database radio button and click Browse.

    The Select Region Startup File dialog box appears.

  7. 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.

  8. Click Finish to close the Define Region dialog box.

Parent topic: Defining an Azure Region


Defining an Azure Batch Region

  1. If you have not already done so, deploy your region startup file to the cross-region database for your Azure deployment. See Adding Configuration Files to the Cross-Region Database. In the following example, we will use the region name JCLDEMO and the region startup file name region_jcldemo.config.
  2. From the Windows Start menu, click the Micro Focus Enterprise Developer > Configuration > Enterprise Server for .NET Admin option to open the Microsoft Management Console (MMC).
  3. 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.

  4. In the Database server instance field of the Define Region dialog box, type the name of your SQL Azure database instance. Click Next.

  5. In the Region name field of the Define Region dialog box, type JCLDEMO. Click Next.

  6. Select the Cross-region database radio button and click Browse.

    The Select Region Startup File dialog box appears.

  7. 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.

  8. 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 File Storage with Enterprise Server for .NET

Azure File Storage allows a storage account to be mounted as a shared drive across the Azure worker roles.

When configuring your Azure Storage account details during the configuration process in the administration tool, you can elect to share an area of storage and map a drive letter to it.

Note: You must use the Classic storage type with Enterprise Server for .NET.

In the above example, a shared drive assigned to the drive letter M (1) will be created and mapped to the path \test (2).

The file storage 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 the drive is persisted in the storage account. Because data written to the drive is stored in the storage account, the data is maintained even if the role instance is recycled. For this reason, File Storage can be used to run an application that needs to use information that will persist between recycles.

In the Enterprise Server for .NET context, a File Storage drive provides an alternative to deploying programs and data into SQL Azure database instances. The main benefit in using an Azure drive over a database deployment is speed.

  • Deploying Artifacts to a File Storage Drive
  • Using a File Storage Drive in a Running Region
Parent topic: Windows Azure Support


Deploying Artifacts to a File Storage Drive

There are various ways to deploy artifacts (programs, mapsets, etc.) to an Azure drive running under an Enterprise Server for .NET Azure instance.

Microsoft AZCopy

Use the AZCopy tool provided by Microsoft. This is a high-speed copy utility that can be used to deploy files to an Azure File Storage instance. The tool and usage descriptions are available from http://azure.microsoft.com/en-gb/documentation/articles/storage-use-azcopy/.

FTP

Install an FTP server onto the monitor roles and use it to upload and download files.

  • Micro Focus does not recommend a particular FTP server, but the server software must be a standalone executable. That is, it must not require installation using MSI or other installer technology.
  • The example below will use a commercial FTP server called Xlight.
  1. Purchase Xlight from http://www.xlightftpd.com/.
  2. Install Xlight onto your local machine and run it.
    1. Configure a user ID and password for the server.
    2. Associate the user account with a drive and path, e.g. v:\.
    3. Save and exit.
  3. Create a self-extracting archive of the Xlight server and configuration using a tool such as 7-Zip or WinZip. For this example, we will put those files in a directory named smallftp and call the archive smallftp.exe.
  4. Copy the smallftp.exe file to the reference directory for your Azure deployment. This is the directory containing files such as EnterpriseServerDotNetAzure.zip which are deployed to Azure as part of various roles.
  5. Create a new command file called startftp.cmd with the following contents:
    :file_check
REM seemap.cmd is created when the share is made available by the role startup processing.
IF EXIST seemap.cmd (GOTO file_exists) ELSE (timeout 5 >NUL)
GOTO file_check

:file_exists
REM Map the drive
call seemap v:
d:
REM Extract the archive
e:smallftp -o"d:\" -y
REM Change to the FTP directory and start the server.
cd smallftp
start xlight -startall
  6. Configure the monitor role in the deployment project to package the two new files startftp.cmd and smallftp.exe.

  7. Configure the monitor startup commands to run startftp.cmd as a background task.

Deploy the system to Azure. When the monitor roles are running, you should be able to connect an FTP client to your FTP server using hostname.cloudapp.net on port 21. Port 21 is exposed as part of the default deployment on the monitor role for this purpose.

You can also use the seedeploy tool to copy files to and from the cloud drive. For File Storage operations, seedeploy requires an FTP server. See seedeploy.

Parent topic: Using Azure File Storage with Enterprise Server for .NET


Using a File Storage Drive in a Running Region

Once a File Storage 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-premises deployment.

Note: You must use the Classic type of Azure Storage with Enterprise Server for .NET.

For example, to use the drive to store application DLLs, 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 seedbdeploy.cmd script used in the ACCT sample deployment example.
  • Once the region startup file is deployed, define the region as described in the Defining an Azure Region topic.
  • 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 File Storage drive to use drive letter M:, you might configure the Application Program Paths node to contain m:\programs.

Parent topic: Using Azure File Storage 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?

SQL Azure, also known as Windows Azure SQL Database, is a database management system (DBMS) based on SQL Server. It is part of the Windows Azure platform. When Enterprise Server for .NET runs in Azure in a Platform-as-a-Service (PaaS) configuration, it uses SQL Azure for its system databases.

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 CICS and JES regions, application objects (DLLs and MODs), and VSAM data files. An Enterprise Server for .NET installation, whether deployed on-premises or in Azure, can access a SQL Azure region and VSAM file databases. Accessing SQL Azure on-premises is significantly slower than accessing it directly from Azure, when the region and SQL Azure database(s) are hosted in the same data center.

By default, Enterprise Server for .NET 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 SQL databases in the left-hand pane.

    The SQL databases screen will be displayed.

  2. Click on the database of interest.
  3. In the Overview section, click the link labeled Show database connection strings, or click Connection strings from the left pane.

    The Connection Strings screen will be displayed.

  4. Copy the connection string from the ADO.NET tab.

    The connection string will be similar to the following, though the parameters listed might be different:

    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 (you might have to edit the connection string and set these yourself)
    • Database=master must not be included in the displayed connection string

    The connection string for each of your SQL Azure databases has the same format, with the appropriate database name instead of master. When you configure a connection string for Enterprise Server for .NET, you will have to specify the database. See SQL Azure Connection Strings for a list of the databases you will need.

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 Azure SQL Database and Data Warehouse firewall rules at https://docs.microsoft.com/en-us/azure/sql-database/sql-database-firewall-configure 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, and experience with System Center Operations Manager.

  • 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 can be any machine that is managed by a SCOM server, including the SCOM server itself.

  1. Open the SCOM administration tool and select the machine to act as the agent.

  2. Right-click, click Security, and check the box to allow the agent to act as a proxy.

  3. On the proxy machine, create a folder called c:\SEE_Azure_MP and copy the following items to it:
    • From the product’s 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 product’s 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 pane 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 click OK.
  9. Click Create again and look for Performance data publisher, give it a name and click 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, use the same name as for CounterSpecifier in the previous step. See the example below, where 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.

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 an 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 instance where you would like to host the region and BANKDEMO database.
    3. Create a database called BANKDEMO in your chosen Azure database server.
    4. Open SQL server Management Studio, or the SQL Server Object Explorer in VS 2013 or later.
    5. Select the BANKDEMO database as the default database.
    6. Open the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\samples\Mainframe\CICS\DotNet\BankDemo\SQL\BankDemoCreateAzure.SQL file.
    7. Execute the SQL.

      The required tables will be created.

  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 (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 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 Azure database instance.
          3. Enter the TCP address of the Azure database 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 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. Note: 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 Azure Database hosted BANKDEMO database.

  3. Package and deploy the Enterprise Server for .NET system to Azure.
    1. Open the Enterprise 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, and 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.

        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.

      • Run bankdemodbdeploy <AzureDatabaseName >, 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. 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 Azure database.
      2. 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.

      3. 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. Ensure the system picks up the XA resource definition correctly, and the DFHPLT transaction was loaded from the database, and not from disk.

  6. Run Bankdemo.
    1. Connect a TN3270 terminal to the listener port in Azure which you configured to be associated with BANKDEMO.

      For example:

      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 Azure database as opposed to disk.
Parent topic: Windows Azure Support


References

Enable Remote Desktop Connection for a Role in Azure | https://www.developer.com/net/connecting-azure-services-using-windows-azure-connect.html
Connecting Azure Services Using Windows Azure Connect | https://docs.microsoft.com/en-us/azure/cloud-services/cloud-services-role-enable-remote-desktop-new-portal
Create a Windows VM in the Azure portal | https://docs.microsoft.com/en-us/azure/virtual-machines/windows/quick-create-portal
Download Windows Azure SDK | https://azure.microsoft.com/en-us/downloads/
Getting Started with Windows Azure SQL Database Using the Azure Management Portal | https://social.technet.microsoft.com/wiki/contents/articles/1884.getting-started-with-windows-azure-sql-database-using-the-windows-azure-management-portal.aspx
How to Create a Storage Account | https://docs.microsoft.com/en-us/azure/storage/common/storage-create-storage-account
Introduction to the VM Role Development Process | http://msdn.microsoft.com/en-us/library/gg466229.aspx
Setting Up Named Authentication Credentials | https://docs.microsoft.com/en-us/azure/vs-azure-tools-setting-up-named-authentication-credentials
What is Azure SQL Database service? | https://docs.microsoft.com/en-us/azure/sql-database/sql-database-technical-overview
Azure SQL Database Guide | http://social.technet.microsoft.com/wiki/contents/articles/sql-azure-database-guide.aspx
SQL Azure Firewall | https://docs.microsoft.com/en-us/azure/sql-database/sql-database-firewall-configure
Using Remote Desktop with Windows Azure Roles | https://docs.microsoft.com/en-us/azure/cloud-services/cloud-services-role-enable-remote-desktop-new-portal
What is Azure? | https://azure.microsoft.com/en-us/overview/what-is-azure/
Windows Azure Platform | https://azure.microsoft.com/
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 5.0


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.
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


Copyright and Legal Information

  • Copyright and Trademarks
Parent topic: Micro Focus Enterprise Server for .NET 5.0


Copyright and Trademarks

© Copyright 1984 - 2022 Micro Focus or one of its affiliates. The software and information contained herein are proprietary to, and comprise valuable trade secrets of, Micro Focus, which intends to preserve as trade secrets such software and information. This software is an unpublished copyright of Micro Focus and may not be used, copied, transmitted, or stored in any manner other than as expressly provided in a written instrument signed by Micro Focus and the user. This software and information or any other copies thereof may not be provided or otherwise made available to any other person.

Micro Focus has made every effort to ensure that this book is correct and accurate, but reserves the right to make changes without notice at its sole discretion at any time. The software described in this document is supplied under a license and may be used or copied only in accordance with the terms of such license, and in particular any warranty of fitness of Micro Focus software products for any particular purpose is expressly excluded and in no event will Micro Focus be liable for any consequential loss.

Portions of some programming examples were produced by Dr. Frank McCown, Harding University Computer Science Dept and are licensed under a Creative Commons License. Such portions have been modified by Micro Focus.

Reference to third party companies, products and web sites is for information purposes only and constitutes neither an endorsement nor a recommendation. Micro Focus provides this information only as a convenience to users. Micro Focus makes no representation whatsoever regarding the content of any other web site or the use of any such third party products. Micro Focus shall not be liable in respect of your use or access to such third party products/web sites.

No part of this publication, with the exception of the software product user documentation contained on a CD-ROM, may be copied, photocopied, reproduced, transmitted, transcribed, or reduced to any electronic medium or machine-readable form without prior written consent of Micro Focus. Contact your Micro Focus representative if you require access to the modified Apache Software Foundation source files.

Licensees may duplicate the software product user documentation contained on a CD-ROM, but only to the extent necessary to support the users authorized access to the software under the license agreement. Any reproduction of the documentation, regardless of whether the documentation is reproduced in whole or in part, must be accompanied by this copyright statement in its entirety, without modification.

U.S. GOVERNMENT RESTRICTED RIGHTS. It is acknowledged that the Software and the Documentation were developed at private expense, that no part is in the public domain, and that the Software and Documentation are Commercial Computer Software provided with RESTRICTED RIGHTS under Federal Acquisition Regulations and agency supplements to them. Use, duplication or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of The Rights in Technical Data and Computer Software clause at DFAR 252.227-7013 et. seq. or subparagraphs (c)(1) and (2) of the Commercial Computer Software Restricted Rights at FAR 52.227-19, as applicable. Contractor is Micro Focus, One Irvington Center, 700 King Farm Boulevard, Suite 400, Rockville, Maryland 20850. Rights are reserved under copyright laws of the United States with respect to unpublished portions of the Software.

2022-02-04

Parent topic: Copyright and Legal Information


DSNRLI Functions used for RRSAF

DSNRLI is typically used as part of a SQL process to connect, open, execute SQL calls, commit or rollback changes, close and disconnect.

Any specified function parameters are read and stored. However, the only parameter used is the subsystem name, which equates to an XA Resource label. Refer to your IBM documentation for details of parameters for each function,

This table describes the DSNRLI functions that can be used to interface with RRSAF.

Function | Description
IDENTIFY | Initializes an XA resource's connection.
SIGNON | Establishes a primary authorization ID and can also establish one or more secondary authorization IDs for a connection.
CREATE THREAD | Allocates the XA resources that are required for an application to issue SQL or IFI requests. This function must complete before the application can execute SQL statements or IFI requests.
SWITCH TO | Directs RRSAF, SQL, or IFI requests to a specified XA resource's subsystem. Use the SWITCH TO function to establish connections to multiple XA resource subsystems from a single task. DSNRLI also provides functions for switching between different subsystems using the SWITCH TO function. On the mainframe, this function directs subsequent SQL calls to the subsystem specified using the ssnm parameter. Use this SWITCH TO followed by IDENTIFY, SIGNON and CREATE THREAD to associate and open another XA Resource. This prevents subsequent SQL from being directed to that resource. The direction is provided by existing SQL functionality. SWITCH TO tells DSNRLI which resource the next calls apply to.
TERMINATE THREAD | Deallocates XA resources that are associated with a plan and were previously allocated for an application using CREATE THREAD. You can then use CREATE THREAD to allocate another plan with the same connection.
TERMINATE IDENTIFY | Terminates an XA resource's connection. Calling the TERMINATE IDENTIFY function is optional. If you do not call it, DSNRLI performs the same functions when the task terminates.
SRRCMIT (CPIC) | Make all changes permanent (or committed) for the current logical unit of work. When a commit operation completes successfully, the changes to all protected resources associated with that logical unit of work are made permanent, and the updates are made available to other users of the protected resources.
SRRBACK (CPIC) | Used to return the protected resources in a logical unit of work to their respective states at the previous sync point. When you request the backout operation, all changes made to protected resources since the last synchronization point are discarded.


Configuring the MVSSPLHK Housekeeping Process

You can configure certain criteria of the MVSSPLHK housekeeping process. Refer to Sample Parameters File for a sample JCL file that contains some of the parameters listed below:
Parameter specification
You can either specify the parameters in-stream or in a configuration file:
SYSIN DD specifies that the parameters are in-stream.
CONFIGI DD DSN=<dataset> specifies the file in which the parameters are stored.
Output files
You can specify an indexed output file that lists all the files archived by the housekeeping process.
INDEXO DD DSN=<dataset> specifies the file in which a list of the archived files is stored.
You can view this file in ESMAC, or with the aid of a copybook (splhkarc.cpy for 5-digit job numbering, or splhkar7.cpy for 7-digit job numbering) you can read the file and output the details to a location of your choice.
Note: When you enable 7-digit job numbering, any existing <dataset> files must be converted to a new 7-digit format in order for them to continue recording a history of the spool files that have been archived. To convert the file, use the CONVERT.JCL file (which is located in the cpylib sub-directory of your product installation directory), changing the data set names to suit your requirements. When run, it calls the MFHKHCOV utility (also supplied). Once converted, the data set will process both 5- and 7-digit job numbers.
A SYSPRINT file is also produced, which contains additional information about the housekeeping process. It specifies the parameters used, the archive locations, and the actions performed on each archived file.
A SYSOUT DD also displays a summary of the process, including its progress, and any errors displayed via the SYSERR DD.
All these files together provide a comprehensive audit trail for the housekeeping process.
The type of archiving to run
Select one of the following:
NONE
The spool clean-up is performed, but no files are archived.
DATA
The spool clean-up is performed, and only the spool data files are archived
FULL
The spool clean-up is performed, and all files are archived. They are moved to a new directory at the archive location, specified by the MF_SPOOL_ARCHIVE_LOC environment variable. The name of the directory consists of the date and time that the archive ran; a directory of this name should not already exist in order for the housekeeping to run.
FULL, ALL
As FULL.
FULL, HELD
The spool clean-up is performed, and only held data sets are archived.
Setting the retain period
You can specify the default retain period (in days) for the housekeeping process:
MAX-RETAIN-PERIOD 006
sets the default retain period to 6 days.
Override the retain period for individual jobs
You can specify a retain period for individual jobs, overriding the default retain period.
JOB_KEEP XXX* 002
JOB_KEEP BCCRSD35 012
JOB_KEEP YYY*
sets the retain period for any job beginning with XXX to 2 days, sets the retain period for the BCCRSD35 job to 12 days, and keeps any jobs beginning with YYY indefinitely.
Override the retain period for jobs in a particular output dataset class
You can specify a retain period for jobs in a particular output data set class, overriding the default retain period.
CLASS A 003 Y
CLASS Z 999 N
sets the retain period for jobs within class A to 3 days, and any older than that are archived, and sets the retain period for jobs in class Z to 999 days (the maximum allowed), and any older than that are not archived.
Override the spool housekeeping run date/time
You can override the date and time that the housekeeping is due to run by setting an environment variable:
MF_SPOOL_HK_TESTDATE=YYYYMMDD
or by passing a parameter to MVSSPLHK when it is invoked:
EXEC PGM=MVSSPLHK,PARM='2014051510303002'
sets the spool housekeeping and archiving to run on 05/15/2014 10:30:30:02.
Note: Only the date portion of this parameter is used when determining the eligibility of a spool file for archiving and/or deleting. The time portion is used when constructing the archive folder name.
Prevent the removal of data sets from an active job
Time-expired, non-active data sets are usually removed from active jobs. To prevent this, include the parameter:
CLEAN-DS-FROM-ACTIVE N
Suppress the creation of profile files
When a data set is to be archived, a profile file (.PRO file) is created; the profile file contains the data set's attributes. This file enables you to view the data set in the Data File Editor, or to use another program to perform file operations upon it. If you do not require profile files for your archived data sets, you can suppress their creation using the following:
MF_SPOOL_HK_WRITE_PROFILES N
Tip: You can also use the MF_SPOOL_HK_WRITE_PROFILES=N environment variable to suppress the creation of profile files.

The following configuration options can be used to reduce the run time of the housekeeping process. It is recommended that a housekeeping run be performed with none of them in effect, after recovery from any system failure, and periodically to ensure the integrity of the spool subsystem. How often this is done depends on the throughput of your batch system.

Suppress the purge of orphaned SYSOUT records
By default, when regular housekeeping has completed, the SPLDSN file is scanned, searching for records for which there is no associated SPLJOB record. You can suppress this search by setting the following configuration option:
MF_SPOOL_HK_ORPHAN_PURGE N
Suppress the purge of old CATALOG records
By default, when regular housekeeping has completed, the CATALOG is scanned, searching for spool record entries older than the maximum retain date, which conform to the standard naming convention (e.g. Y2017.S0323.S083544.J0001000.D00001.SYSPRINT). You can suppress this search by setting the following configuration option:
MF_SPOOL_HK_CATALOG_PURGE N

Alternatively, you can extend this search to encompass ALL spool data sets, regardless of their name, by setting the configuration option:

MF_SPOOL_HK_CATALOG_PURGE A
Warning: If you choose to extend the search in this way, and have a large catalog, spool housekeeping run times will increase significantly.
Suppress the check for orphaned LEX records

By default, when regular housekeeping has completed, the spool data directory is scanned, searching for LEX files (used internally by the job submission and restart functions) for which there is no associated SPLJOB record. You can suppress this search using the following configuration option:

MF_SPOOL_HK_LEX_SCAN N
Tip: You can also use the MF_SPOOL_HK_LEX_SCAN=N environment variable to suppress the search.
Suppress the detail records on SYSPRINT
By default, every successful housekeeping action is reported on SYSPRINT, which can result in a very large report. You can suppress the detail records by using the following configuration option:
MF_SPOOL_HK_SYSPRINT_DETAIL N
Related tasks
Spool Housekeeping
Related reference
Running the MVSSPLHK Housekeeping Process
Sample Parameters File


Running the MVSSPLHK Housekeeping Process

The following JCL job step demonstrates how to run the MVSSPLHK housekeeping process using parameters stored in an existing data set (TEST.CONFIG):
//ARCHIVE  EXEC PGM=MVSSPLHK
//SYSPRINT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//SYSERR   DD SYSOUT=*
//INDEXO   DD DSN=TEST.ARCHIVE.XREF,DISP=SHR
//CONFIGI  DD DSN=TEST.CONFIG,DISP=SHR

If a parameter file is specified, any in-stream housekeeping parameters are ignored.

The following JCL job step demonstrates how to run the MVSSPLHK housekeeping process using parameters specified in-stream:

//ARCHIVE  EXEC PGM=MVSSPLHK
//SYSPRINT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//SYSERR   DD SYSOUT=*
//INDEXO   DD DSN=TEST.ARCHIVE.XREF,DISP=SHR
//* SYSIN or CONFIGI dataset contains the program parameters
//SYSIN  DD *
* --------------------------------------------------------
*   SPOOL HOUSEKEEPING CONFIGURATION FILE
* --------------------------------------------------------
*   GENERAL MAXIMUM RETAIN PERIOD (DAYS)
 MAX-RETAIN-PERIOD 006
* --------------------------------------------------------
*   RETAIN PERIODS FOR SPECIFIC JOB NAMES
 JOB_KEEP   XXX*    001
* --------------------------------------------------------
*   ARCHIVE TYPE REQUIRED
*            NONE,
*            DATA ( SPOOL DATA FILES ONLY )
*            FULL (CASSPOOL, MVSSPOOL AND CATALOG SO SPOOL
*                  ARCHIVES CAN BE VIEWED IN ES. ALL DATASETS ,
*                  HELD, OUTPUT and PRINTED )
*            FULL,ALL (same as ‘FULL’)
*            FULL,HELD (HELD DATASETS ONLY)
* --------------------------------------------------------
 ARCHIVE    TYPE FULL

* --------------------------------------------------------
*   ARCHIVE LOCATION - use the environment variable
*   and append the archive date-time to the location
* --------------------------------------------------------
* ARCHIVE   LOC C:\estest\sphktest\archdir\
* --------------------------------------------------------

* --------------------------------------------------------
*   ARCHIVE LOCATION - use region start-up file's "Use spool archive" property
* --------------------------------------------------------
*   ARCHIVE   LOC C:\SpoolArchive
*          or LOC sql://myinst/JES/?folder=/JCLDEMO/SpoolArchive;type=folder
* --------------------------------------------------------

*   CLASS SPECIFIC OVERRIDES (PREVIOUSLY IN SPOOLHK.CPY)
*   ONLY INCLUDE THOSE THAT ARE DIFFERENT FROM THE MAX-RETAIN-PERIOD
*CLASS ID<SPACE>RETAIN PERIOD<NNN><SPACE>ARCHIVE<Y/N>
*
 CLASS A 003 Y
 CLASS B 003 Y
 CLASS C 003 Y
 CLASS Z 999 Y
* --------------------------------------------------------
/*
Related tasks
Spool Housekeeping
Related reference
Configuring the MVSSPLHK Housekeeping Process
Sample Parameters File


DSNRLI Overview

Important: It is strongly recommended that only dynamically registered XA switch modules are used with DSNRLI. If statically registered switches must be used, please ensure that a SRRCMIT or SRRBACK call occurs before a TERMINATE THREAD call. This is required as the DSNRLI implementation has no state knowledge of static RM participation in the global transaction.

DSNRLI is the language interface load module for the DB2 Resource Recovery Services attachment facility (RRSAF). It provides the interface to RRSAF only through the DSNRLI entry point. This entry point provides explicit service connection requests for any XA resource, including WebSphere MQ.

The interface is separate from the mainframe version of RRSAF, which provides closer control over DB2 connections. The interface is designed to provide the necessary functions to help ease application migration.

On the mainframe, the RRSAF language interface module (DSNRLI) is an extension to DB2 and, when used by a program, all DB2 SQL calls pass through one of its entry points, DSNHLIR. However, IBM's RRSAF is not available in DB2 LUW. Micro Focus provides its own version of this module to ease migration of customer applications. However, because it is not part of DB2, it does not provide all of the functions that the mainframe version does.

The Call Attachment Facility (CAF) DSNALI interface provides basic DB2 connection control functions: Connect, Open, Close etc.

In addition to the functions used to call transaction processing APIs, the Micro Focus DSNRLI functionality provides the Common Program Interface - Communications (CPIC) utility functions SRRCMIT (commit) and SRRBACK (rollback)

You can use either the appropriate XA resource COMMIT statement or the CPIC SRRCMIT function to commit work to RRSAF applications. Likewise, you can use either the appropriate XA resource ROLLBACK statement or the CPIC SRRBACK function to roll back work.

Use appropriate XA resource COMMIT and ROLLBACK statements if:

  • The only recoverable resource your application accesses is data that is managed by a single XA resource.
  • The address space where syncpoint processing initiates is the same as the address space of your application.

Use CPIC SRRCMIT and SRRBACK functions if:

  • Your application accesses other recoverable resources, or syncpoint processing and XA resource access are initiated from different address spaces.
  • You are using multiple XA Resources. Use DSNRLI to link those resources to your unit of work and then use SRRCMIT/SRRBACK to commit or rollback work changes.


DSNRLI Work Unit Functions

DSNRLI is typically used as part of the SQL process to connect, open, execute SQL calls, commit, rollback, close, and disconnect. However, the Micro Focus DSNRLI functions used in this process are shown in the table:

Process | DSNRLI Function | tx_CALL
Connect | IDENTIFY | tx_associate
 | SIGNON | tx_open
Open | CREATE THREAD | tx_begin
Commit | SRRCMIT | tx_commit
Rollback | SRRBACK | tx_rollback
Close | TERMINATE THREAD | tx_end, tx_close
Disconnect | TERMINATE IDENTIFY | none

For user executed SQL calls, use existing SQL architecture.

Multiple XA Resources can be used in a single unit of work. In those cases, the application should use DSNRLI IDENTIFY, SIGNON and CREATE THREAD calls to associate each additional XA Resource.


DSNRLI Functionality

DSNRLI Overview

DSNRLI Functions used for RRSAF

DSNRLI Work Unit Functions

Limitations Using Micro Focus DSNRLI

Related information
DSNALI Functionality
About XA Resources


Sample Parameters File

The following is a sample parameters file that you can edit, and then use when running the MVSSPLHK spool housekeeping process.

//SETUP01 JOB 'SPHK',MSGCLASS=A,CLASS=A,MSGLEVEL=(1,1)
//*--------------------------------------------------------
//DEL     EXEC PGM=IEFBR14
//DEL1    DD DSN=TEST.CONFIG,SPACE=(TRK,1),DISP=(MOD,DELETE)
//*==========================================================
//*       CONFIGURATION FILE
//*==========================================================
//DEFCFG   EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY
//SYSUT1   DD *
* --------------------------------------------------------
*   SPOOL HOUSEKEEPING CONFIGURATION FILE
* --------------------------------------------------------
*   GENERAL MAXIMUM RETAIN PERIOD
MAX-RETAIN-PERIOD 003
* --------------------------------------------------------
*   RETAIN PERIODS FOR SPECIFIC JOB NAMES
* --------------------------------------------------------
JOB_KEEP   XXX*    1
* --------------------------------------------------------
*   PREVENT DATA SETS BEING REMOVED FROM ACTIVE JOB
* --------------------------------------------------------
CLEAN-DS-FROM-ACTIVE N
* --------------------------------------------------------
*   ARCHIVE TYPE REQUIRED
*            NONE
*            DATA ( SPOOL DATA FILES ONLY )
*            FULL (CASSPOOL, MVSSPOOL AND CATALOG SO SPOOL
*                  ARCHIVES CAN BE VIEWED IN ES. ALL DATASETS,
*                  HELD, OUTPUT and PRINTED)
*            FULL,ALL (same as FULL)
*            FULL,HELD (HELD DATASETS ONLY)
* --------------------------------------------------------
ARCHIVE    TYPE FULL,ALL

* --------------------------------------------------------
*   ARCHIVE LOCATION - use the environment variable
* --------------------------------------------------------
*   ARCHIVE   LOC D:\estest\sphktest\archdir\
* --------------------------------------------------------

* --------------------------------------------------------
*   ARCHIVE LOCATION - use region start-up file's "Use spool archive" property
* --------------------------------------------------------
*   ARCHIVE   LOC C:\SpoolArchive
*          or LOC sql://myinst/JES/?folder=/JCLDEMO/SpoolArchive;type=folder
* --------------------------------------------------------

*   CLASS SPECIFIC OVERRIDES (PREVIOUSLY IN SPOOLHK.CPY)
*   ONLY INCLUDE THOSE THAT DIFFER FROM THE MAX-RETAIN-PERIOD
*   OR WHERE ARCHIVING IS NOT REQUIRED FOR A CLASS
CLASS A 3 Y
CLASS B 3 Y
CLASS C 3 Y
CLASS D 999 N
CLASS E 999 N
CLASS F 999 N
CLASS G 999 N
CLASS H 999 N
CLASS I 999 N
CLASS J 999 N
CLASS K 999 N
CLASS L 999 N
CLASS M 999 N
CLASS N 999 N
CLASS O 999 N
CLASS P 999 N
CLASS Q 999 N
CLASS R 999 N
CLASS S 999 N
CLASS T 999 N
CLASS U 999 N
CLASS V 999 N
CLASS W 999 N
CLASS X 999 N
CLASS Y 999 N
CLASS Z 4 N
CLASS 0 5 N
CLASS 1 999 N
CLASS 2 999 N
CLASS 3 999 N
CLASS 4 999 N
CLASS 5 999 N
CLASS 6 999 N
CLASS 7 0 N
CLASS 8 999 N
CLASS 9 999 N
*---------------------------------------------------------
*   SUPPRESS CREATION OF PROFILE FILES FOR ARCHIVED DATASETS
*---------------------------------------------------------
MF_SPOOL_HK_WRITE_PROFILES N
* --------------------------------------------------------
//SYSUT2  DD DSN=TEST.CONFIG,SPACE=(TRK,1),UNIT=SYSDA,
//        DCB=(LRECL=80,RECFM=LSEQ,DSORG=PS),DISP=(NEW,CATLG)
//*===========================================================
//*        ARCHIVE XREF FILE
//*===========================================================
//DEFXREF  EXEC PGM=IDCAMS
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  *
    DELETE 'TEST.ARCHIVE.XREF'
    IF MAXCC = 8 THEN SET MAXCC=0
    DEFINE CLUSTER(NAME(TEST.ARCHIVE.XREF)     -
                   KEYS(61 0) -
                   RECSZ(401 401) -
                   INDEXED -
                   SHAREOPTIONS(2 3)       -
                   CYL(40 10))
/*
//*===========================================================
//
Related tasks
Spool Housekeeping
Related reference
Configuring the MVSSPLHK Housekeeping Process
Running the MVSSPLHK Housekeeping Process


MLDAP ESM Module

The MLDAP ESM Module is the ESM Module that enables LDAP servers to be used as External Security Managers for Enterprise Server.

MLDAP (Micro Focus LDAP) is an interface to multiple LDAP providers. It lets the MLDAP ESM Module communicate with a variety of LDAP directories, such as Microsoft Active Directory. The directory can be located on the same system as Enterprise Server, which is often the case for development workstations. (Windows development systems can use AD/LDS (formerly ADAM), Microsoft's version of Active Directory for applications, for example.) Or the directory can be remote, which is more common in production environments.

Within the LDAP directory, you define users, user groups, resource classes, and resources, and these objects contain the attributes used to make security checks (for the Verify, Auth, and XAuth procedures). Micro Focus defines a schema for these objects and their attributes, but in many cases you can adapt an existing directory for at least part of this information, for example in order to reuse an existing repository of user information.

When the MLDAP ESM Module is invoked by ESF Manager to process a security request, it searches the configured LDAP repository for relevant rules and applies whatever it finds. Like other ESM Modules, it can return a definite result if it finds an applicable rule, or an indefinite result otherwise. (See the discussion of Security Function Return Codes.) Since multiple ESM Modules can be configured, this allows configurations such as user and resource information in separate directories, or the resolution of some requests using LDAP and others using some other ESM.

Version 2 of the MLDAP ESM Module , released with Enterprise Server 2.3 and some hotfixes for 2.2 Update 2, includes a new algorithm for matching resource access control rules with security checks. This new algorithm is used by default. It provides better performance and more intuitive behavior in a number of common cases, and enables new features such as Username Substitution. Because some existing customers with complex, ambiguous security rules might see changes in behavior with the new algorithm, the method used in version 1 of the MLDAP ESM Module is still available and can be selected using a configuration option. See Compatibility Rule Matching for more information.

Related tasks
Using The ESM Modules


Limitations Using Micro Focus DSNRLI

Using the Micro Focus implementation of DSNRLI has these limitations and restrictions:

  • The Micro Focus implementation of DSNRLI is not technically an extension of the XA specification, so it does not provide some of the functions the mainframe version does. Those not implemented include:
    • SIGNON
    • AUTH SIGNON
    • CONTEXT SIGNON - The connection details, including user ID, are included in the XA resource definition in Enterprise Server. Direct calls or SQL application handling calls are not made to the database. so these are no-operation calls.
    • SET_ID
    • SET_CLIENT_ID - See CONTEXT SIGNON.
    • FIND_DB2_SYSTEMS - A function to search DB2 systems is not needed since the required systems and XA resources are defined in the Enterprise Server configuration.
    • (Implicit connections) - On the mainframe, if the IDENTIFY, SIGNON, CREATE THREAD sequence is not called before the first EXEC SQL call, then DSNRLI performs an implicit connection. In this implementation, since DSNRLI is not aware of the EXEC SQL calls, it does not make an implicit connection. The application must make explicit calls to DSNRLI to associate specific XA resources with a unit of work.
    • DSNHLI, DSNHLR - The entry points for making SQL calls are not used. The applications must make EXEC SQL calls and use existing SQL functionality.
    • DSNWLI, DSNWLIR - The entry points for making Instrumentation Facility Interface (IFI) calls are not used, since the IFI is not available.
  • An issue with DB2 LUW prevents jobs that include 1 Phase Commit (1PC) programs from running after a 2 Phase Commit (2PC) program using DSNRLI has run in the same initiator. That is, programs that run under IKJEFTxx or use DSNALI fail if a DSNRLI program using the same DB2 Switch Module has previously run in the same initiator. A symptom of the problem would be a message sequence such as:
    JCLCM0188I JOB01001 MFIAFN2  JOB  STARTED
CASXO0001S XA Resource Manager initialization error. Resource DSN open failed, reason -00003
CASXO0016S DSN XA interface initialization failure
MVSXM0036S JOB01001 MFIAFN2  Database OPEN call failed "PROGRAM NAME"

    where MFIAFN2 is a job with a IKJEFT01 step using 'DSN SYSTEM(DSN)' and a program using DSNRLI and the same XA Resource (DSN) had previously run in the same initiator.

    To address this issue, append TOC=P to the open string specified in the XA resource configuration in Enterprise Server region settings. For example, the correct open string is DB=SAMPLE,UID=admin,PWD=passwd,TOC=P.


DSNALI Functionality

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
DSNRLI Functionality
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 configuration 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