webMethods EntireX

Designer

Version 10.7

October 2020
This document applies to webMethods EntireX Version 10.7 and all subsequent releases.

Specifications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions.

Copyright © 1997-2020 Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, USA, and/or its subsidiaries
and/or its affiliates and/or their licensors.

The name Software AG and all Software AG product names are either trademarks or registered trademarks of Software AG and/or
Software AG USA, Inc. and/or its subsidiaries and/or its affiliates and/or their licensors. Other company and product names mentioned
herein may be trademarks of their respective owners.

Detailed information on trademarks and patents owned by Software AG and/or its subsidiaries is located at
[Link]

Use of this software is subject to adherence to Software AG's licensing conditions and terms. These terms are part of the product
documentation, located at [Link] and/or in the root installation directory of the licensed product(s).

This software may include portions of third-party products. For third-party copyright notices, license terms, additional rights or re-
strictions, please refer to "License Texts, Copyright Notices and Disclaimers of Third-Party Products". For certain specific third-party
license restrictions, please refer to section E of the Legal Notices available under "License Terms and Conditions for Use of Software AG
Products / Copyright and Trademark Notices of Software AG Products". These documents are part of the product documentation,
located at [Link] and/or in the root installation directory of the licensed product(s).

Use, reproduction, transfer, publication or disclosure is prohibited except as specifically provided for in your License Agreement with
Software AG.

Document ID: EXX-EEXXWORKBENCH-107-20220422

Table of Contents
Software AG Designer ....................................................................................................... v
1 About this Documentation .............................................................................................. 1
Document Conventions ............................................................................................. 2
Online Information and Support ............................................................................... 2
Data Protection ........................................................................................................... 3
2 Scope of the Designer ...................................................................................................... 5
Editors ........................................................................................................................ 6
EntireX Wrappers ....................................................................................................... 7
Software AG IDL Extractors ...................................................................................... 9
Other Components ................................................................................................... 10
3 Supported File Types ..................................................................................................... 11
Input Files ................................................................................................................. 12
Output Files .............................................................................................................. 13
4 Server Mapping Files for Natural .................................................................................. 15
Server Mapping Files in the Designer ...................................................................... 17
When is a Server Mapping File Required? ............................................................... 18
Source Control of Server Mapping Files .................................................................. 18
Comparing Server Mapping Files ............................................................................ 18
5 Server Mapping Files for COBOL ................................................................................. 19
Server Mapping Files in the Designer ...................................................................... 20
When is a Server Mapping File Required? ............................................................... 21
Migrating Server Mapping Files .............................................................................. 26
Source Control of Server Mapping Files .................................................................. 27
Comparing Server Mapping Files ............................................................................ 27
6 Server Mapping Deployment Wizard ........................................................................... 29
Introduction .............................................................................................................. 31
Undeploying a Server Mapping ............................................................................... 31
Preferences ............................................................................................................... 35
Command-line Mode ............................................................................................... 39
7 EntireX IDL Tester ......................................................................................................... 41
Calling the IDL Tester .............................................................................................. 42
Using the Broker and RPC User ID/Password ......................................................... 44
8 Using EntireX Custom Wrappers .................................................................................. 47
Define EntireX Custom Wrappers ............................................................................ 48
Running a Custom Wrapper .................................................................................... 56
9 Using EntireX in the Designer Command-line Mode ................................................... 57
Command Line under Windows ............................................................................. 58
Command Line under Linux ................................................................................... 59
List of all Commands ............................................................................................... 59
10 EntireX IDL Preferences .............................................................................................. 63
Defaults for EntireX Wrappers ................................................................................. 64
Storing IDL Properties in an External File ............................................................... 65

iii
iv
Software AG Designer

The EntireX design-time user interface is implemented as part of Software AG Designer and
delivered as an Eclipse feature. It provides various wrappers, IDL extractors, editors and testers
for generating and testing RPC communication between RPC servers and RPC client applications.

Scope Lists the EntireX components of the Designer, with links to more
information.
Supported File Types EntireX file types supported by Designer.
Server Mapping Files for Handling server mapping files for Natural in the Designer. Server mapping
Natural files are used at runtime to marshal and unmarshal the RPC data stream.
This document provides information on source control, comparing etc. of
server mapping files.
Server Mapping Files for Handling server mapping files for COBOL in the Designer. Server mapping
COBOL files are used at runtime to marshal and unmarshal the RPC data stream.
This document provides information on migration, source control,
comparing etc. of server mapping files.
Deployment Wizard How to synchronize server mapping files with the Server Mapping
Deployment Wizard.
IDL Tester Using the EntireX IDL Tester.
Custom Wrappers How to define your own template-based wrappers.
Command-line Mode Using EntireX design-time features from a Designer command line.
IDL Preferences Provide defaults for EntireX Wrappers (Broker ID...) and specify location
of external file to store IDL properties for export/import.

See also Installing EntireX Design-time outside the Designer. This document is applicable if you want
to install the EntireX design-time separately, that is, not as part of the full webMethods EntireX
installation.

If you are not yet familiar with Eclipse, see the Eclipse online help at
[Link] or start the Designer and then choose Help > Help Contents.
General information on Eclipse can then be found under Workbench User Guide. When working
with the Designer, the online help also provides help for the currently installed Software AG
products; this can be found under Software AG Designer Guides.

You can find an introduction to the Designer on the Software AG Documentation website at
[Link] under Guides for Shared Tools > Working with Software AG
Designer.

v
vi
1 About this Documentation

■ Document Conventions ...................................................................................................................... 2

■ Online Information and Support ........................................................................................................... 2
■ Data Protection ................................................................................................................................. 3

1
About this Documentation

Document Conventions

Convention Description
Bold Identifies elements on a screen.
Monospace font Identifies service names and locations in the format [Link],
APIs, Java classes, methods, properties.
Italic Identifies:

Variables for which you must supply values specific to your own situation or
environment.
New terms the first time they occur in the text.
References to other documentation sources.
Monospace font Identifies:

Text you must type in.

Messages displayed by the system.
Program code.
{} Indicates a set of choices from which you must choose one. Type only the information
inside the curly braces. Do not type the { } symbols.
| Separates two mutually exclusive choices in a syntax line. Type one of these choices.
Do not type the | symbol.
[] Indicates one or more options. Type only the information inside the square brackets.
Do not type the [ ] symbols.
... Indicates that you can type multiple options of the same type. Type only the
information. Do not type the ellipsis (...).

Online Information and Support

Product Documentation

You can find the product documentation on our documentation website at [Link]
[Link].

In addition, you can also access the cloud product documentation via [Link]
[Link]. Navigate to the desired product and then, depending on your solution, go to “Developer
Center”, “User Center” or “Documentation”.

Product Training

You can find helpful product training material on our Learning Portal at [Link]
[Link].

2 Designer
 About this Documentation

Tech Community

You can collaborate with Software AG experts on our Tech Community website at [Link]
[Link]. From here you can, for example:

■ Browse through our vast knowledge base.

■ Ask questions and find answers in our discussion forums.
■ Get the latest Software AG news and announcements.
■ Explore our communities.
■ Go to our public GitHub and Docker repositories at [Link] and ht-
tps://[Link]/publishers/softwareag and discover additional Software AG resources.

Product Support

Support for Software AG products is provided to licensed customers via our Empower Portal at
[Link] Many services on this portal require that you have an account.
If you do not yet have one, you can request it at [Link] Once
you have an account, you can, for example:

■ Download products, updates and fixes.

■ Search the Knowledge Center for technical information and tips.
■ Subscribe to early warnings and critical alerts.
■ Open and update support incidents.
■ Add product feature requests.

Data Protection

Software AG products provide functionality with respect to processing of personal data according
to the EU General Data Protection Regulation (GDPR). Where applicable, appropriate steps are
documented in the respective administration documentation.

Designer 3
4
2 Scope of the Designer

■ Editors ............................................................................................................................................ 6
■ EntireX Wrappers .............................................................................................................................. 7
■ Software AG IDL Extractors ................................................................................................................ 9
■ Other Components .......................................................................................................................... 10

5
Scope of the Designer

Editors

IDL Editor
A Software AG IDL file contains definitions of the interface between client and server. The
IDL file is used by Software AG wrappers to generate RPC clients, RPC servers and tester etc.
on the basis of these definitions. The IDL file can be edited by the IDL Editor provided by plug-
ins for Eclipse.
Merging and Refactoring Software AG IDL
IDL refactoring is a process that checks all programs and structures in a single library if they
contain identical groups. All identical groups are extracted in a single structure in the same
library, and replaced with a structure reference. If a structure exists that is identical to the
structure to be created, all references will point to the existing structure and a new one will
not be created. Two groups are identical if each group has the same number and order of
parameters, and each parameter in one group has the same name and the same type as the
corresponding parameter in the other group. IDL refactoring can be performed on single or
multiple IDL files.
XML Mapping Editor
The EntireX XML Mapping Editor allows you to map XML document structures to IDL libraries,
programs and parameters. The mappings can be defined for the request and response to the
server application, or from the server to the client. The input for the XML Mapping Editor can
be a Software AG IDL file and/or an IDL-XML mapping file (perhaps produced by a previous
XML Mapping Editor session or by importing a WSDL file, XML Document or XML Schema).
The output is an IDL-XML mapping file, other XML structure definitions (such as sample XML
files), and perhaps a created or changed IDL file.

6 Designer
 Scope of the Designer

EntireX Wrappers

In EntireX terms, a wrapper is a tool contained in the Designer to generate interface objects based
on a Software AG IDL file and additional wrapping properties. The following wrappers are
provided:

C Wrapper
EntireX C Wrapper provides access to RPC-based components from C applications. It enables
you to develop both client and server applications.
COBOL Wrapper
EntireX COBOL Wrapper provides access to RPC-based components from COBOL applications.
It enables you to develop both client and server applications.
Custom Wrappers
The EntireX Custom Wrappers are user-configurable, template-based wrappers and need a
Software AG IDL file, a template (e.g., client or server) and the Software AG IDL Compiler.
DCOM Wrapper
The EntireX DCOM Wrapper generates DCOM-enabled components using RPC technology.
This so-called “wrapping” makes it possible to treat existing applications as ActiveX compon-
ents.
.NET Wrapper
The EntireX .NET Wrapper provides access to RPC servers for .NET client applications and
access to .NET servers for any RPC client. The .NET Wrapper generation tools of the Designer
take as input a Software AG IDL file, which describes the interface of the RPC, and generates
C# classes that implement the methods and data types of the interface.
Integration Server Wrapper
The webMethods Integration Server Wrapper generates Integration Server adapter services
and listeners from a Software AG IDL file within an Integration Server connection definition.
Java Wrapper
The EntireX Java Wrapper provides access to EntireX RPC-based components from Java ap-
plications. With EntireX Java RPC you can develop both client and server applications written
in Java. Java applets can also be used as EntireX RPC clients.
Java Wrapper for Natural
The EntireX Java Wrapper for Natural allows you to generate EntireX Java client interface
objects from Natural subprograms in a NaturalONE project in Eclipse. The generated Java
client interface objects can be used by Java application developers to access Natural server
components, using EntireX/Natural RPC.
Natural Wrapper
The Natural Wrapper allows you to develop Natural client applications that access RPC-based
server components, and to create Natural RPC server skeletons you can use as a basis to write
a Natural RPC server that can be accessed by RPC clients.

Designer 7
Scope of the Designer

PL/I Wrapper
The EntireX PL/I Wrapper provides access to RPC-based components from PL/I applications.
It enables you to develop both client and server applications.
Web Services Wrapper
The EntireX Web Services Wrapper is a wizard that generates and optionally deploys Web
services (Designer file with extension .aar) to offer an RPC server - for example a COBOL or
Natural RPC server - as a Web service. The generated XML/SOAP mapping file (Designer file
with extension .xmm) can also be used to enable RPC clients - for example a COBOL or Natural
client - consuming (or calling) a Web service.
Web Services Wrapper for Natural
The EntireX Web Services Wrapper for Natural allows you to develop Web Services that access
Natural server components, using EntireX/Natural RPC.
XML/SOAP Wrapper
The EntireX XML/SOAP Wrapper enables XML-based communication to EntireX/Natural RPC
servers and communication from EntireX/Natural RPC clients to XML-based servers.

8 Designer
 Scope of the Designer

Software AG IDL Extractors

An extractor is a tool contained in the Designer to extract a Software AG IDL file. The following
extractors are provided:

IDL Extractor for COBOL

The Software AG IDL Extractor for COBOL enables you to extract the interface of a COBOL
server and transforms it into a Software AG IDL and a Software AG server mapping file. Both
files are required to provide access for any RPC client to the COBOL server.
IDL Extractor for Integration Server
The Software AG IDL Extractor for webMethods Integration Server is a wizard that reads a
package from the Integration Server and generates a Software AG IDL file from existing services
and nodes. Each service results in a program in the IDL file. All parameters of the services are
mapped to an IDL alphanumeric data type, available as variable (AV) or fixed (An) length.
From EntireX Adapter version 10.5, you can select individual services and nodes; with earlier
versions all services and nodes are extracted.
IDL Extractor for Natural
The Software AG IDL Extractor for Natural extracts a Software AG IDL definition from a
Natural source in a Natural project in Eclipse, or from an object within a Natural RPC environ-
ment.
IDL Extractor for PL/I
The Software AG IDL Extractor for PL/I extracts a Software AG IDL file from a PL/I source.
The PL/I source can be located in the file system or accessed remotely within a PL/I RPC envir-
onment definition.
IDL Extractor for WSDL
The Software AG IDL Extractor for WSDL is a wizard that generates Web service client artifacts
from a WSDL file. With these artifacts, EntireX RPC client applications can access external
Web services.
IDL Extractor for XML Document
The Software AG IDL Extractor for XML Document generates an IDL File and a related XML
mapping file (XMM) from a given XML document.
IDL Extractor for XML Schema
The Software AG IDL Extractor for XML Schema generates an IDL File and a related XML
mapping file (XMM) from given XML schema files.

Designer 9
Scope of the Designer

Other Components

CentraSite Integration
Web services created with EntireX can be published to CentraSite. CentraSite offers enhanced
registry functionality, and also repository functionality that enables you to store Web services
artifacts and register interdependencies for impact analysis.
Default Broker View
The EntireX Default Broker View is part of the Designer. It displays the status of the EntireX
Default Broker and the active RPC Services registered to it.
UDDI Registration
EntireX UDDI Registration is a tool with which you can register a Web service with any UDDI
registry for which you have an account.

10 Designer
3 Supported File Types

■ Input Files ...................................................................................................................................... 12

■ Output Files ................................................................................................................................... 13

11
Supported File Types

Input Files

The following table lists the file types that the Designer can use as input. Some of the file types
may have different content. The content determines which files you can generate. The actions in
the context menu depend on the file type.

File Type Content Generated Files

cvm Server mapping file that completes the related IDL of the same
name with server mapping information to successfully call the
target RPC server customer program. Contains COBOL mapping
(see Server Mapping Files for COBOL) or Natural mapping (see
Server Mapping Files for Natural).
idl Software AG IDL for RPC, see Software AG IDL File in the IDL C client, C server, Java client,
Editor documentation. Java server, Java tester,
COBOL client, COBOL server,
C# client, DCOM object, XMM
file, PL/I client, PL/I server.
svm Server mapping files with extension .svm are no longer supported
at design time by the Designer. You can still use them at runtime
in a server-side mapping container. All special COBOL syntax and
features supported by server mapping files with extension .svm
are also covered by server mapping files with extension .cvm. See
When is a Server Mapping File Required? We recommend
migrating .svm files to .cvm files. See Migrating Server Mapping
Files under Server Mapping Files for COBOL in the Designer
documentation.
wsdl Web service description file. IDL file, XMM mapping file.
xml XML document. IDL file, XMM mapping file.
xmm EntireX XMM file with element mapping.
xmm EntireX XMM file with attribute mapping.
xmm EntireX XMM file with user-defined mapping.
xmm EntireX XMM file with SOAP mapping. WSDL file.
xsd XML Schema file. IDL file, XMM mapping file.

12 Designer
 Supported File Types

Output Files

The following table lists the file types generated by the Designer.

File Type Content Generated from

aar Service archive for Web Services Stack. IDL file with XML mapping.
cvm Server mapping file (Natural | COBOL) that completes COBOL source; Natural source.
the related IDL of the same name with server mapping
information to successfully call the target RPC server
customer program.
idl Software AG IDL for RPC. Import XSD, import XML, import
WSDL.
wsdl Web service description file. IDL file.
xml XML document as test document for the XML Tester. IDL file.
xmm EntireX XMM file with element mapping. IDL file with XML mapping.
xmm EntireX XMM file with attribute mapping. IDL file with XML mapping.
xmm EntireX XMM file with user-defined mapping. IDL file with XML mapping.
xmm EntireX XMM file with SOAP mapping. IDL file with XML mapping.

Designer 13
14
4 Server Mapping Files for Natural

■ Server Mapping Files in the Designer .................................................................................................. 17

■ When is a Server Mapping File Required? ............................................................................................ 18
■ Source Control of Server Mapping Files ............................................................................................... 18
■ Comparing Server Mapping Files ........................................................................................................ 18

15
Server Mapping Files for Natural

Server mapping enables the RPC server to correctly support special Natural syntax such as
REDEFINEs, special Natural Mapping Editor operations, etc. If one of these elements is used the
IDL Extractor for Natural automatically extracts a server mapping file (Designer file with extension
.cvm) in addition to the IDL file (interface definition language). Also the Natural Wrapper may
generate a server mapping file for RPC server generation. The server mapping file is used at
runtime to marshal and unmarshal the RPC data stream. A server mapping file is wrapped into
the client interface objects when an RPC client is generated. Therefore, it is important the server
mapping (.cvm) is available before creating any RPC client component, that is, the server program
must be extracted or generated first.

16 Designer
 Server Mapping Files for Natural

Server Mapping Files in the Designer

The following rules apply to a server mapping file for Natural:

■ Mapping files have the extension .cvm.

■ The mapping file has to relate to an appropriate IDL file. Always keep the IDL file and the
mapping file together in the same folder.
■ The mapping file is created if required by the Natural Wrapper | Extractor. See When is a
Server Mapping File Required?
■ If an IDL file has a corresponding mapping file, at least one of the IDL programs in the IDL file
requires server-mapping information to correctly call the target server. For those IDL programs,
there is a server mapping (corresponding to a line) in the server mapping file.
■ If there is an IDL file but no corresponding mapping file, there is no IDL program that requires
server mapping information.

Designer 17
Server Mapping Files for Natural

When is a Server Mapping File Required?

IDL Extractor for Natural

Server Mapping
Natural Syntax Natural Mapping Editor Reqired More Information
REDEFINE yes Extracting Natural REDEFINES in the IDL Extractor
for Natural documentation
all Rename of program yes Renaming a Program
all Multiple interfaces yes Extracting Multiple Interfaces
all Set constant yes Setting Natural Parameters to Constants
all Suppress yes Suppressing Natural Parameters
Other combinations no

Natural Wrapper

Server Mapping
Natural Wrapper Required More Information
IDL program name is not a valid Natural yes Step 2: Customize Natural Server Names
name and is therefore adapted, or the under Using the Natural Wrapper for the
Natural program name is customized Server Side within NaturalONE

Source Control of Server Mapping Files

Because server mapping files (Designer files with extension .cvm) contain text data only, a server
mapping file is text-based (although it is not intended for human consumption). Therefore, you
can include it in your source control management together with the IDL file and the Natural
source(s) as a triplet that should always be kept in sync.

Comparing Server Mapping Files

For server mapping files (Designer files with extension .cvm), you can use a third party file/text
compare tool to check if two files are identical.

A server mapping entry (corresponding to a line in a server mapping file) contains a creation
timestamp at offset 276 (decimal) in the format YYYYMMDDHHIISST. The precision is 1/10 of a second.

18 Designer
5 Server Mapping Files for COBOL

■ Server Mapping Files in the Designer .................................................................................................. 20

■ When is a Server Mapping File Required? ............................................................................................ 21
■ Migrating Server Mapping Files .......................................................................................................... 26
■ Source Control of Server Mapping Files ............................................................................................... 27
■ Comparing Server Mapping Files ........................................................................................................ 27

19
Server Mapping Files for COBOL

Server mapping enables the RPC server to correctly support special COBOL syntax such as
REDEFINEs, SIGN LEADING and OCCURS DEPENDING ON clauses, LEVEL-88 fields, etc. If one of these
elements is used, the IDL Extractor for COBOL automatically extracts a server mapping file (De-
signer file with extension .cvm) in addition to the IDL file (interface definition language). Also,
the COBOL Wrapper may generate a server mapping file for RPC server generation. The server
mapping is used at runtime to marshal and unmarshal the RPC data stream. A server mapping
file is wrapped into the client interface objects when an RPC client is generated. Therefore, it is
important the server mapping (.cvm) is available before creating any RPC client component, that
is, the server program must be extracted or generated first.

Server Mapping Files in the Designer

The following rules apply to a server mapping file for COBOL in the Designer:

■ Mapping files have the extension .cvm.

■ The mapping file has to relate to an appropriate IDL file. Always keep the IDL file and the
mapping file together in the same folder.
■ The mapping file is created if required by the COBOL Wrapper | Extractor. See When is a
Server Mapping File Required?
■ If an IDL file has a corresponding mapping file, at least one of the IDL programs in the IDL file
requires server-mapping information to correctly call the target server. For those IDL programs,
there is a server mapping (corresponding to a line) in the server mapping file.
■ If there is an IDL file but no corresponding mapping file, there is no IDL program that requires
server mapping information.
■ The mapping is wrapped into the client interface objects when an RPC client is generated. The
mapping must available before you create any RPC client component, that is, the COBOL server
program must be extracted or generated first.
■ The mapping is sent at runtime to the target RPC server with the RPC request.
■ Only point-to-point connections are allowed. The RPC client with the server mapping in its client
interface object can only call one specific target COBOL server program. If you want to replace
the COBOL end point by another end point, for example Java, you need to rebuild all the RPC
clients without the server mapping wrapped into their client interface object. This is because a
Java server end point does not recognize server mappings - the RPC request would be rejected
by the Java server.

20 Designer
 Server Mapping Files for COBOL

When is a Server Mapping File Required?

■ IDL Extractor for COBOL
■ COBOL Wrapper

IDL Extractor for COBOL

A server mapping file (Designer file with extension .cvm) is generated by the IDL Extractor for
COBOL if the COBOL server program is of a specific interface type, contains specific COBOL
syntax, or the IDL interface is redesigned (Suppress, Set constant, etc.) in the COBOL Mapping
Editor.

COBOL Server
Mapping Mapping
Interface Type COBOL Syntax Editor Required More Information
CICS all yes CICS with DFHCOMMAREA Calling Convention
DFHCOMMAREA - In different to Out under COBOL Mapping
and In different to Editor in the IDL Extractor for COBOL
Out documentation (1) and the following COBOL
server examples for CICS input message
different to the CICS output message:

■ Example 1: Redefines
■ Example 2: Buffer Technique
■ Example 3: COBOL SET ADDRESS
Statements

CICS Channel all yes CICS with Channel Container Calling

Container Convention
CICS Large Buffer all yes CICS with DFHCOMMAREA Large Buffer Interface
COBOL Converter all yes COBOL Converter (2)
and In different to
Out

Designer 21
Server Mapping Files for COBOL

COBOL Server
Mapping Mapping
Interface Type COBOL Syntax Editor Required More Information
IMS MPP (IMS all yes IMS MPP Message Interface (IMS Connect)
Connect)
IMS BMP all yes IMS BMP with Standard Linkage Calling
Convention
CICS OCCURS clause, Set Arrays yes See Set Arrays (Fixed <-> Unbounded) for
DFHCOMMAREA, see COBOL Tables (Fixed <-> interface type DFHCOMMAREA
CICS Channel with Fixed Size Unbounded) (In same as Out, In different to Out) | Large
Container, CICS Buffer (In same as Out, In different to Out) |
Large Buffer, IMS Channel Container | IMS Connect | COBOL
MPP (IMS Connect), Converter
COBOL Converter (In same as Out, In different to Out) (1, 2)
all OCCURS clause, Map to no See Map to for interface type
see COBOL Tables DFHCOMMAREA (In different to Out) |
with Fixed Size Large Buffer (In different to Out) | Channel
Container | IMS Connect | COBOL
Converter (In different to Out) (1,2)
Map to In, See Map to In, Out, InOut for interface type
Out, InOut DFHCOMMAREA (In same as Out) | Large
Buffer (In same as Out) | Batch | IMS BMP |
In same as Out) (1,2)
CICS COBOL group Set multiple yes See Set Multiple Possible Output (MPO)
DFHCOMMAREA, data items used possible Structures for interface type
CICS Channel in optional output DFHCOMMAREA (In same as Out, In
Container, CICS manner, see structures different to Out) | Large Buffer (In same as
Large Buffer, IMS Optional COBOL (MPO) Out, In different to Out) | Channel
MPP (IMS Connect), Group Data Items Container | IMS Connect | COBOL
COBOL Converter Converter (In same as Out, In different to
Out) (1,2)
all COBOL group Map to no See Map to for interface type
data items DFHCOMMAREA (In different to Out) |
Large Buffer (In different to Out) | Channel
Container | IMS Connect | COBOL
Converter (In different to Out) (1,2)
Map to In, See Map to In, Out, InOut for interface type
Out, InOut DFHCOMMAREA (In same as Out) | Large
Buffer (In same as Out) | Batch | IMS BMP |
In same as Out) (1,2)
all OCCURS Map to yes See Map OCCURS DEPENDING ON for
DEPENDING ON interface type DFHCOMMAREA (In
clause, see different to Out) | Large Buffer (In different
COBOL Tables to Out) | Channel Container | IMS Connect |
with Variable Size COBOL Converter (In different to Out) (1,2)

22 Designer
 Server Mapping Files for COBOL

COBOL Server
Mapping Mapping
Interface Type COBOL Syntax Editor Required More Information
- DEPENDING ON Map to In, See Map OCCURS DEPENDING ON for
Clause Out, InOut interface type DFHCOMMAREA
(In same as Out) | Large Buffer (In same as
Out) | Batch | IMS BMP | In same as Out) (1,2)
CICS REDEFINES Set multiple yes Set Multiple Possible Output (MPO) Structures
DFHCOMMAREA, clause, see possible for interface type DFHCOMMAREA (In
CICS Channel REDEFINES output same as Out, In different to Out) | Large
Container, CICS Clause (MPO) Buffer (In same as Out, In different to Out) |
Large Buffer, IMS structures Channel Container | IMS Connect (1,2)
MPP (IMS Connect), Map to COBOL REDEFINES can be used in several
COBOL Converter ways:

■ Select REDEFINE Paths for interface type

DFHCOMMAREA (In different to Out) |
Large Buffer (In different to Out) |
Channel Container | IMS Connect |
COBOL Converter (In different to Out)
■ Map to Multiple IDL Interfaces for interface
type DFHCOMMAREA (In different to
Out) | Large Buffer (In different to Out) |
Channel Container | IMS Connect |
COBOL Converter (In different to Out)

Map to In, COBOL REDEFINES can be used in several

Out, InOut ways:

■ Select REDEFINE Paths for interface type

DFHCOMMAREA (In same as Out) |
Large Buffer (In same as Out) | COBOL
Converter (In same as Out
■ Map to Multiple IDL Interfaces for interface
type DFHCOMMAREA (In different to
Out) | Large Buffer (In same as Out) |
COBOL Converter (In same as Out)

Batch, IMS BMP REDEFINES Map to In, yes COBOL REDEFINES can be used in serveral
clause, see Out, InOut ways:
REDEFINES
■ Select REDEFINE Paths for interface type
Clause
Batch | IMS BMP
■ Map to Multiple IDL Interfaces for interface
type Batch | IMS BMP

Designer 23
Server Mapping Files for COBOL

COBOL Server
Mapping Mapping
Interface Type COBOL Syntax Editor Required More Information
all SIGN LEADING yes
[SEPARATE]
clause, see SIGN
LEADING and
TRAILING
SEPARATE Clauses
all SIGN TRAILING yes
[SEPARATE]
clause, see SIGN
LEADING and
TRAILING
SEPARATE Clauses
all SYNCHRONIZED yes
clause, see
SYNCHRONIZED
Clause
all all Rename of yes See Map to Multiple IDL Interfaces for interface
program type DFHCOMMAREA
(In same as Out, In different to Out) | Large
Buffer (In same as Out, In different to Out) |
Channel Container | Batch | IMS BMP |
IMS Connect | COBOL Converter
(In same as Out, In different to Out) (1,2)
all ■ Condition Set to yes See Set COBOL Data Items to Constants for
Names - constant interface type DFHCOMMAREA (In same
Level-88 Data as Out, In different to Out) | Large Buffer (In
Items same as Out, In different to Out) | Channel
■ Container | Batch | IMS BMP |
COBOL Data
IMS Connect | COBOL Converter (In same
Items Expecting
as Out, In different to Out) (1,2)
Single Constant
Values

all See Unneeded Suppress yes Suppress Unneeded COBOL Data Items for
COBOL Data interface type DFHCOMMAREA (In same
Items as Out, In different to Out) | Large Buffer (In
same as Out, In different to Out) | Channel
Container | Batch | IMS BMP |
IMS Connect | COBOL Converter (In same
as Out, In different to Out) (1,2)
other combinations no

Notes:

24 Designer
 Server Mapping Files for COBOL

1. For interface types DFHCOMMAREA and Large Buffer, COBOL server programs use either
the same data structure on input and output (“In same as Out”), or overlay the input data
structure with a different output data structure (“In different to Out”). See COBOL Mapping
Editor.
2. For interface type COBOL Converter, COBOL input and output is either described by the same
layout (“In same as Out”) or the input is overlaid by a different output layout (“In different to
Out”). See COBOL Mapping Editor.

COBOL Wrapper

A server mapping file (Designer file with extension .cvm) is generated by the COBOL Wrapper if
an RPC server is generated (1,2) and at least one IDL program meets the criteria in the table below.

Server
Mapping
Interface Type IDL Type COBOL Wrapper Required More Information
CICS Large all yes CICS with DFHCOMMAREA Large Buffer Interface
Buffer under COBOL Server Interface Types in the
COBOL Wrapper documentation
CICS Channel all yes CICS with Channel Container Calling
Container Convention
IMS BMP all yes IMS BMP with Standard Linkage Calling
Convention
all IDL yes array-definition under Software AG IDL
unbounded Grammar in the IDL Editor documentation
array
all IDL yes group-parameter-definition under
unbounded Software AG IDL Grammar in the IDL Editor
group documentation
all all IDL program name is yes Customize Automatically Generated Server
not a valid COBOL Names under Generating COBOL Source Files
name and is from Software AG IDL Files in the COBOL
therefore adapted, or Wrapper documentation
the COBOL program
name is customized
other combinations no

(1)
Server mapping files are never generated for RPC clients.

Designer 25
Server Mapping Files for COBOL

Migrating Server Mapping Files

This section covers the following topics:

■ Introduction
■ Prerequisites
■ Step 1: Rename the Server-side Mapping File
■ Step 2: Remove the Server-side Mapping Files on Target RPC Server
■ Step 3: Rebuild and Deploy all RPC Clients

Introduction

EntireX 10.5 was the last version where it was possible to create server-side mapping files (.svm)
as optional output of the IDL Extractor for COBOL or COBOL Wrapper at design time.

EntireX 10.7 and later creates client-side mapping files (.cvm) at design time, which are easier to
handle. This can be an important criterion, for example, if the RPC server is hosted in a mainframe
environment and you do not have access to mainframe development resources. The following
tasks are not required:

■ deploying the server mapping files to the RPC server

■ setting up a server-side mapping container in the mainframe environment
■ change management of server-side mapping files in the mainframe environment

At runtime, server-side mapping files (.svm) are still supported in the RPC server, but we recom-
mend you migrate them to client-side mapping files (.cvm). You can migrate step-by-step, for each
IDL file and related server mapping.

Prerequisites

The following prerequisites must be met to migrate server-side mapping files (Designer files with
extension .svm) to client-side mapping files (Designer files with extension .cvm).

All EntireX components involved in the migration must be version 9.7 or higher:

■ the target RPC server z/OS (CICS | Batch | IMS), CICS ECI, IMS Connect
■ the webMethods EntireX Adapter for Integration Server. See EntireX and your webMethods Integ-
ration Server Applications
■ the RPC client runtimes

Note: Client-side mapping files are not supported by RPC clients generated with the DCOM
Wrapper and COBOL Wrapper.

26 Designer
 Server Mapping Files for COBOL

Step 1: Rename the Server-side Mapping File

Rename the extension .svm to .cvm in the Designer. This results in a client-side mapping file.

Step 2: Remove the Server-side Mapping Files on Target RPC Server

Remove the server-side mapping files in the server-side mapping container of the target RPC
server. See Undeploying Server-side Mapping Files in the RPC server documentation for z/OS (CICS,
Batch, IMS) | CICS ECI | IMS Connect | BS2000.

Note: For IMS Connect and CICS ECI connections with webMethods EntireX Adapter for
Integration Server, this step is not required.

Step 3: Rebuild and Deploy all RPC Clients

1. Re-create (wrap, build, compile etc.) all involved RPC clients (1) using the related IDL file to
wrap the client-side mapping files into the client interface objects. See EntireX Wrappers.
2. Test the RPC clients with client-side mapping files.
3. If necessary, re-deploy the RPC clients with client-side mapping files.

(1)
This includes all variants of connections of the webMethods EntireX Adapter for Integration
Server. See Integration Server Wrapper.

Source Control of Server Mapping Files

Because server mapping files (Designer files with extension .cvm) contain text data only, a server
mapping file is text-based (although it is not intended for human consumption). Therefore, you
can include it in your source control management together with the IDL file and the COBOL
source(s) as a triplet that should always be kept in sync.

Comparing Server Mapping Files

For server mapping files (Designer files with extension .cvm), you can use a third party file/text
compare tool to check if two files are identical.

A server mapping entry (corresponding to a line in a server mapping file) contains a creation
timestamp at offset 276 (decimal) in the format YYYYMMDDHHIISST. The precision is 1/10 of a second.

Designer 27
28
6 Server Mapping Deployment Wizard

■ Introduction .................................................................................................................................... 31
■ Undeploying a Server Mapping .......................................................................................................... 31
■ Preferences ................................................................................................................................... 35
■ Command-line Mode ........................................................................................................................ 39

29
Server Mapping Deployment Wizard

See also Undeploying Server-side Mapping Files for CICS ECI | IMS Connect.

Note: To synchronize server mapping files to the webMethods EntireX Adapter for Integra-
tion Server you need to update your Adapter connection. See Step 3: Create or Update an
Adapter Connection in the Integration Server Wrapper documentation.

30 Designer
 Server Mapping Deployment Wizard

Introduction

Using the wizard requires an active RPC server. Also, the Deployment Service of the RPC server
must be properly configured. See the platform-specific documentation for more information:

■ z/OS, see Deployment Service for CICS | Batch | IMS.

■ BS2000, see Deployment Service in the EntireX RPC Server for BS2000 documentation.

Undeploying a Server Mapping

To undeploy a server-side mapping file with the wizard, follow the steps below:

■ Step 1: Check the File Extension

■ Step 2: Start the Wizard
■ Step 3a: Create a New Deployment Environment
■ Step 3b: Define the Connection to the Deployment Service and Undeploy
■ Step 4: Select an Existing Deployment Environment and Undeploy

Step 1: Check the File Extension

Make sure the extension of the server mapping file is changed from .svm to .cvm before you start
the wizard. This is the first step when you migrate server mapping files from the server-side to
the client-side. See Migrating Server Mapping Files.

Designer 31
Server Mapping Deployment Wizard

Step 2: Start the Wizard

To start the Server Mapping Deployment Wizard, select an IDL file and from the context menu
choose Deploy/Synchronize Server Mapping....

To continue, press Next with one of the following choices:

■ If you are using the Server Mapping Deployment Wizard for first time with no predefined de-
ployment environment preferences, continue with Step 3a: Create a New Deployment Environ-
ment below.

32 Designer
 Server Mapping Deployment Wizard

■ If deployment environments are already defined, you may also continue with Step 4: Select an
Existing Deployment Environment and Undeploy.

Step 3a: Create a New Deployment Environment

If no deployment environments are defined, you only have the option to create a new deployment
environment.

Select Create a new deployment environment and press Next to continue with Step 3b: Define
the Connection to the Deployment Service and Undeploy.

Step 3b: Define the Connection to the Deployment Service and Undeploy

Use this page to define a connection to the deployment service of the RPC server.

Designer 33
Server Mapping Deployment Wizard

Enter the required fields:

1. Broker Parameters Broker ID and Server Address, which will have the default format. The last
part (broker service) of the server address must always be "DEPLOYMENT".
2. The EntireX Authentication parameters describe the settings for the broker. These parameters
apply if the broker is running with EntireX Security.
3. The RPC Server Authentication parameters describe the settings for the RPC server. These
parameters apply if the RPC server is running with security. See Impersonation under CICS |
Batch | IMS in the respective RPC Server documentation.
4. The given Timeout value must be in the range from 1 to 9999 seconds (default: 60).

Press Finish to undeploy. Undeployment of the server mapping is successful if the wizard ends.
No confirmation message is given.

34 Designer
 Server Mapping Deployment Wizard

Step 4: Select an Existing Deployment Environment and Undeploy

Use this page to select the deployment environment (that is, the RPC server) to which you want
to undeploy.

Check the option Choose an existing deployment environment and select a deployment environ-
ment from the list. Press Finish to undeploy. Undeployment is successful if the wizard ends. No
confirmation message is given.

Preferences

In the preferences for the Server Mapping Deployment Wizard you define deployment environ-
ments, a connection to the Deployment Service of the RPC server. See Deployment Service for
z/OS (CICS, Batch, IMS) | BS2000 in the respective RPC Server documentation The following sec-
tions are offered:

■ Create a New Deployment Environment

■ Edit an Existing Deployment Environment
■ Remove an Existing Deployment Environment

The deployment environment is managed from the deployment environment Preferences page.
The deployment environments can be created, edited and removed. The deployment environment
will be used for the selection lists in the Deployment Wizard. To manage these deployment envir-
onments, open the Preferences page:

Designer 35
Server Mapping Deployment Wizard

Create a New Deployment Environment

To create a new deployment environment

■ Press Insert.

36 Designer
 Server Mapping Deployment Wizard

Edit an Existing Deployment Environment

To edit an existing deployment environment

■ Select the table row and press Edit. If multiple entries are selected, the first entry is used.

Designer 37
Server Mapping Deployment Wizard

Remove an Existing Deployment Environment

To remove an existing deployment environment

■ Select the table row and press Remove. Multiple selections are possible.

38 Designer
 Server Mapping Deployment Wizard

Command-line Mode

The command -deploy:cobol is provided to synchronize server mapping files between Designer
and RPC server, using the Designer in command-line mode. See Using EntireX in the Designer
Command-line Mode for general information. Synchronizing or undeploying server mapping files
from the RPC server is part of Migrating Server Mapping Files.

To undeploy previously deployed server mapping information

1 Make sure the extension of the server mapping file is changed from .svm to .cvm before you
start the wizard. This is the first step when you migrate server mapping files.
2 Execute the command -deploy:cobol with the IDL file.

Command-line Options

Task Command Option Description

Synchronize -deploy:cobol -environment Target environment. Name of the COBOL deployment
SVM files. environment or an RPC server description.
-brokeruser User used for broker authentication (optional).
-brokerpassword Password used for broker authentication (optional).
-rpcuser User used for RPC server authentication (optional).
-rpcpassword Password used for RPC server authentication
(optional).

Note: Run the command from the directory containing the IDL file. If no server-side mapping
file is found (Designer file with extension .svm), the previously deployed server mapping
information related to the IDL file will be removed on the server side (undeployed). See
Undeploying Server-side Mapping Files in the RPC server documentation for CICS, Batch, IMS.

Example

-deploy:cobol /SVMDeployTests/idls/[Link] /SVMDeployTests/idls/[Link] ↩

/SVMDeployTests/idls/[Link]
-environment ibm2:3980@RPC/RPCALL/DEPLOYMENT
-brokeruser EXXUSR1
-brokerpassword EXX$PWD1

Designer 39
40
7 EntireX IDL Tester

■ Calling the IDL Tester ....................................................................................................................... 42

■ Using the Broker and RPC User ID/Password ....................................................................................... 44

41
EntireX IDL Tester

The IDL Tester is an easy-to-use utility to communicate with EntireX RPC Servers. It acts as an RPC
client application, taking as input an IDL file. It is useful for testing extracted or generated artifacts
such as the IDL file, XML mapping file for Web services, server mapping files Natural | COBOL
etc. together with the RPC Server. It verifies the mapping of the data and all involved components
up to the endpoint (RPC Server, Web Service, IBM MQ, etc.).

Note: With the Java Wrapper you can also generate IDL-related test classes into a Java
project. See Using the IDL Tester under Using the Java Wrapper.

Calling the IDL Tester

To call the IDL Tester

■ Select an IDL file, and from the context menu, choose Software AG IDL Tester. This launches
the IDL Tester.

The dialog contains fields for Broker ID and server address and buttons, a message area for gen-
eral output and error messages, and a parameter area with the input and output parameters. The
fields for the input parameters have a white background and the fields for the output parameters
are disabled and have a gray background.

Broker ID and server address are displayed as specified in the properties of the IDL file; they can
be modified. To modify the server address, it is sufficient to enter the server; RPC/CALLNAT will
be added automatically.

42 Designer
 EntireX IDL Tester

Button Explanation
Call Perform the remote procedure call.
Ping Ping the broker and the RPC server.
Open Conversation Open a conversational RPC (only visible if no conversation is open).
Commit Conversation Close the conversational RPC and commit the conversation (only visible after Open
Conversation).
Abort Conversation Close the conversational RPC and abort the conversation (only visible after Open
Conversation).
Reset Reset the message area and the parameters.
Exit Exit the IDL Tester.

The bottom of the dialog contains text fields for the parameters of the Software AG IDL file. These
fields are prefixed with the group level, field name and type. IN and INOUT parameters can be edited,
OUT parameters cannot be modified. The fields for INOUT and OUT parameters are updated after a
successful call. Array elements must be separated by a semicolon. The last array element behind
a semicolon will be used to fill up the array completely, e.g. (I4/5) and value 1;2 results in 1;2;2;2;2,
but value 1;2; results in 1;2;;;.

The File Menu contains the entries Options and Exit. The Options dialog allows you to set user
credentials. See Using the Broker and RPC User ID/Password.

To execute the remote call via EntireX Broker

■ Use the Call button or press Return in one of the input parameter fields.

If the Broker returns errors (a BrokerException is thrown), the error message is displayed in the
Messages area.

To ping the Broker and the RPC server

■ Use the Ping button.

To delete the entries in the message area and the parameter fields

■ Use the Reset button.

Designer 43
EntireX IDL Tester

Using the Broker and RPC User ID/Password

EntireX supports two user ID/password pairs: a broker user ID/password pair and an (optional)
RPC user ID/password pair sent from RPC clients to RPC servers. With EntireX Security, the broker
user ID/password pair can be checked for authentication and authorization.

The RPC user ID/password pair is designed to be used by the receiving RPC server. This compon-
ent's configuration determines whether the pair is considered or not. Useful scenarios are:

■ Credentials for Natural Security

■ Impersonation in the respective RPC Server documentation
■ Web Service Transport Security with the RPC Server for XML/SOAP, see XML Mapping Files
■ Service execution with client credentials for EntireX Adapter Listeners, see Configuring Listeners
■ etc.

Sending the RPC user ID/password pair needs to be explicitly enabled by the RPC client. If it is
enabled but no RPC user ID/password pair is provided, the broker user ID/password pair is inher-
ited to the RPC user ID/password pair.

With the check box Natural Logon, sending the RPC user ID/password pair is enabled for the IDL
Tester. If you do so, we strongly recommend using SSL/TLS. See SSL/TLS, HTTP(S), and Certificates
with EntireX.

To use the broker and RPC user ID/password

1 Specify User and Password as Broker Authentication in the Options dialog.

44 Designer
 EntireX IDL Tester

2 Check the check box Natural Logon to enable sending the RPC user ID/password pair.
3 If different user IDs and/or passwords are used for broker and RPC, enter RPC User ID and
RPC Password to provide a different RPC user ID/password pair.

4 By default the library name sent to the RPC server is retrieved from the IDL file (see
library-definition under Software AG IDL Grammar in the IDL Editor documentation). The
library name can be overwritten. This is useful if communicating with a Natural RPC server.
Specify a Natural Library.

Designer 45
46
8 Using EntireX Custom Wrappers

■ Define EntireX Custom Wrappers ....................................................................................................... 48

■ Running a Custom Wrapper .............................................................................................................. 56

47
Using EntireX Custom Wrappers

The EntireX Custom Wrappers are user-configurable, template-based wrappers and need:

■ a Software AG IDL file

■ a template (for example, client or server)
■ the IDL Compiler

Naturally, existing .plugin files from former EntireX installations, called Designer Plug-ins, can be
migrated. The Custom Wrapper definitions are stored in the current Eclipse workspace and can
be managed in the preferences. Any changes in the Custom Wrapper definitions require a restart
of the Designer to take effect. This chapter covers the following topics:

Define EntireX Custom Wrappers

The EntireX Custom Wrappers are managed in the Custom Wrapper preferences page.

The central panel lists all known (active or inactive) Custom Wrappers, that is, all Custom Wrappers
that are found in the current workspace. You can create a new empty Custom Wrapper, copy, edit
or remove an existing Custom Wrapper or migrate your existing .plugin file from a former EntireX
installation.

■ Creating a New Custom Wrapper

■ Parameters
■ Parameter Values
■ Wildcards

48 Designer
 Using EntireX Custom Wrappers

Creating a New Custom Wrapper

To create a new Custom Wrapper

1 Choose Insert...

Designer 49
Using EntireX Custom Wrappers

2 Enter the fields. The Name is a required field and must be unique, because it is the identifier
for the Custom Wrapper. This name occurs on the Custom Wrapper Properties page and will
be used for the command line with the prefix minus sign.

Field Description
Name Used as the Custom Wrapper menu item text.
Author and Copyright Important if you want to share your Custom Wrapper with other users.
Template Name of the template file to be used by the Software AG IDL Compiler. Use a
fully qualified file name.
Command Executable command file name. Default is empty and means the Software AG
IDL Compiler will be executed.
Options Batch parameters. They are sent to the Software AG IDL Compiler.
Parameter Parameters (constant or modifiable) to call the Custom Wrapper.

3 Optionally, add some parameters as described in the following sections.

To add parameters

■ Choose Add...

50 Designer
 Using EntireX Custom Wrappers

A new dialog with default values is displayed. See section Parameters for a description of
the individual fields. Modifiable parameters automatically appear with an appropriate label
and GUI widget on the Custom Wrapper IDL properties tab.

To edit parameters (see Parameters)

1 Select the parameter to edit in the table.

2 Choose Edit...

or

Double click on the parameter in the table.

A new dialog with the current parameter values is displayed. See section Parameters for a
description of the individual fields. For all strings in the fields Type Values and Parameter
Value, you can also use wildcards. Wildcards are like variables for actual values that may
change with the platform or in other properties tabs. See the list of Wildcards.
3 Choose OK to save your entries and close the dialog or Cancel to close the dialog without
saving.

To remove parameters

1 Select the parameters to remove in the table.

2 Choose Remove.

Multiple selections are possible.

Designer 51
Using EntireX Custom Wrappers

To change the parameter order

1 Select the parameter to edit in the table.

2 Use the Up and Down buttons to change the order of the parameters.

Parameters

Parameters consist of the following fields:

Field Purpose
Parameter The parameter identifier, as required by the erxidl template (must not contain whitespace
characters; often in uppercase).
Description The textual description of this parameter, as displayed in the associated Custom Wrapper
IDL properties tab. Human-readable, may contain whitespace characters and short
examples.
Type Dialog box of possible GUI representations of the Parameter Values.
Type Values The possible values that may be assigned to the parameter, in the form
<parametername>=<value>. Values are separated by a semicolon.
Parameter Value Default value for the GUI representation, must be one of the values listed in the Type
Values field.
Global Flag for the parameter value. True (default) means the parameter value is for all IDL files,
false means the parameter value is IDL specific (stored in IDL properties).

Parameter Values

Parameter “types” are GUI representations of the parameter values in the IDL properties tab for
this Custom Wrapper. They can be:

Entry Purpose, Usage

Check box Will draw a check box in the Custom Wrapper IDL properties tab. Type Values must have
two values, separated by a semicolon. The first value is taken if the check box is checked, the
second value is taken if the check box is cleared.
Combo box Will draw a combo box (drop-down list) in the Custom Wrapper IDL properties tab. Type
Values must have at least one entry, or multiple entries separated by semicolon. An entry may
be:

■ a simple string (without the “=” character), which is displayed as an entry in the box and is
sent to the Software AG IDL Compiler.
■ a pair "<val>=<string>", where <string> is displayed in the combo box, but <val> is
sent to the Software AG IDL Compiler.

Constant Will not generate a GUI element in the associated IDL properties tab. Type Values just has
one string, which is sent to the Software AG IDL Compiler.

52 Designer
 Using EntireX Custom Wrappers

Entry Purpose, Usage

Text Will show a text field in the associated Custom Wrapper IDL properties tab. The text field
content is taken for the Software AG IDL Compiler command-line construction. If whitespace
characters are typed in the text field, the Software AG IDL Compiler command-line portion
is protected by double quotes. Type values may contain a string representing as default value
for the text field.

Designer 53
Using EntireX Custom Wrappers

Wildcards

Wildcards start with the % (percent sign). Implemented wildcards:

Wildcard Name Purpose Example Value

%brokerid Get the Broker ID from the General tab. localhost:1971
%server Get the server address from the General RPC/SRV1/CALLNAT
tab.
%serverclass Get the server class identifier from the RPC
General tab.
%servername Get the server name from the General SRV1
tab.
%service Get the service identifier from the CALLNAT
General tab.
%idlfile Get the current IDL file (as absolute path C:\Examples\[Link]
name) as selected in the Designer.
%idlname Get the current IDL file (just the file [Link]
name with extension, no path) as
selected in the Designer.
%pureidlname Get the current IDL file name without example
path and without the file extension.
%idlpath Get the current IDL file path (without C:\Examples
the IDL file name) as selected in the
Designer.
%xmlfile Get the current XML mapping file name C:\Examples\[Link]
from the XML tab.
%msdotnetenv Path of Microsoft Visual Studio C:\Program Files\Microsoft Visual Studio 10
environment as set in the Tools Options \Common7\IDE\
menu item.
%netfrmdir Path for installation of the .NET C:\WINDOWS\[Link]\Framework\
framework. v2.0.50727
%version Get the EntireX version. 10.7
%osname Get the operating system name, taken Windows Server 2019
from the Java system property [Link].
%osarch Get the operating system architecture, x86
taken from the Java system property
[Link].
%osversion Get the operating system version, taken 5.1
from the Java system property
[Link].
%fileseparator Get the platform-specific file separator \
character, taken from the Java system
property [Link].

54 Designer
 Using EntireX Custom Wrappers

Wildcard Name Purpose Example Value

%fileencoding Get the platform-specific file encoding, Cp1252
taken from the Java system property
[Link].
%pathseparator Get the platform-specific path separator ;
character, taken from the Java system
property [Link].
%username Get the current user name, taken from administrator
the Java system property [Link].
%userhome Get the assigned user home directory, C:\Documents and Settings\administrator
taken from the Java system property
[Link].
%userdir Get the current user directory, taken C:\Documents and Settings\administrator\My
from the Java system property Documents
[Link].

To duplicate an existing Custom Wrapper

1 Select the Custom Wrapper in the list.

2 Proceed as described in Creating a New Custom Wrapper and press Duplicate instead of In-
sert....

A new Custom Wrapper named Copy of <name> is displayed in the list.

3 Modify the entries as described in Creating a New Custom Wrapper.

To edit an existing Custom Wrapper

1 Select the Custom Wrapper in the list.

2 Proceed as described in Creating a New Custom Wrapper and press Edit... instead of Insert....
3 Modify the entries as described in Creating a New Custom Wrapper.

To remove an existing Custom Wrapper

1 Select the Custom Wrapper in the list.

2 Press Remove.

To migrate an existing .plugin file from a previous EntireX Installation

1 Proceed as described in Creating a New Custom Wrapper and press Migrate... instead of In-
sert....
2 Browse to the location of the .plugin file and select the file to migrate.

Designer 55
Using EntireX Custom Wrappers

3 In the ensuing dialog, modify the entries as described in Creating a New Custom Wrapper.
4 Make sure the template file can be accessed correctly.

Running a Custom Wrapper

To start the Custom Wrapper in GUI

1 Select an IDL file.

2 Open the context menu, choose Other > Generate Via Template and select the desired item
(for example, New).

When the Custom Wrapper is started, the Designer starts the Software AG IDL Compiler and
feeds it with a template, the IDL file name and (optional) parameters.

The parameters are inserted for the Software AG IDL Compiler in the form
<parametername>=<value>. If wildcards were used for the values, they are resolved to the actual
values when the Custom Wrapper was called.

To start the Custom Wrapper in command-line mode

■ See Using EntireX in the Designer Command-line Mode for the general syntax of the command
line.

The command for the Custom Wrapper is -xxx, where xxx is the case-sensitive name of the Custom
Wrapper. If the name contains blanks, use -"xxx".

Example:

-NEW /Demo/[Link]

The result of the Custom Wrapper is written to Standard Out.

56 Designer
9 Using EntireX in the Designer Command-line Mode

■ Command Line under Windows .......................................................................................................... 58

■ Command Line under Linux ............................................................................................................... 59
■ List of all Commands ........................................................................................................................ 59

57
Using EntireX in the Designer Command-line Mode

For EntireX, the Designer can also be used from a command line. The command entered depends
on your operating system.

■ Under Windows, the command line is available with the starter [Link].
■ Under Linux, the command line is available with script [Link].
■ Under both operating systems, the command line is also available with the command for Eclipse
using the Java Runtime.

In all alternatives, a command is followed by a list of file names and a list of options. The file names
may contain an asterisk (*) as a wildcard. The options are key-value pairs, where the key starts
with a hyphen. The command selects the Wrapper or Extractor to use. The detailed options for
each command are described in the respective Wrapper or Extractor section. Using -help as
command lists all available commands with a short description. Using -help <command> lists the
options of the command.

For a detailed description of each Wrapper or Extractor, see the documentation of this component.
Throughout these detailed descriptions we use <workbench> as a general placeholder for the actual
starter of the Designer. This can be [Link], [Link], or the Eclipse starter.

Command Line under Windows

Enter the following command, replacing <EntireX HOME> with your EntireX installation directory:

<EntireX HOME>\bin\[Link] <command> [ <file> [ <file> ... ] ] [<options>]

This is the preferred method to start the EntireX design-time from the command line. Alternatively,
you can use

"%ECLIPSE_HOME%\eclipsec" -application
[Link] -data %WORKSPACE% -nosplash
<command> [ <file> [ <file> ... ] ] [<options>]

where ECLIPSE_HOME is the Eclipse installation directory

WORKSPACE is the Eclipse workspace directory.

58 Designer
 Using EntireX in the Designer Command-line Mode

Command Line under Linux

Enter the following command:

/<Install_Dir>/EntireX/bin/[Link] <command> [ <file> [ <file> ... ] ]

[<options>]

or

eclipse -vm $ECLIPSE_HOME/bin/ -application

[Link] -data $WORKSPACE -nosplash
<command> [ <file> [ <file> ... ] ] [<options>] -vmargs
-[Link]=/<Install_Dir>/EntireX/common/conf/LKey/[Link]

where ECLIPSE_HOME is the Eclipse installation directory

WORKSPACE is the Eclipse workspace directory.

List of all Commands

Command Description Syntax / Examples

-c:client Generate an RPC client from an IDL file. Using the C Wrapper in
-c:server Generate an RPC server from an IDL file. Command-line Mode

-cobol:client Generate a COBOL RPC client from an IDL Using the COBOL Wrapper
file. in Command-line Mode
-cobol:server Generate a COBOL RPC server from an IDL
file.
-dcom:generate Generate the DCOM Wrapper object(s) for Using the DCOM Wrapper in
the specified IDL file(s). Command-line Mode
-deploy:cobol Synchronize server-side mapping files to the Command-line Mode
specified environment. See Server Mapping
Files for COBOL.
-extract:natural Extract the Natural sources or objects from a Using the IDL Extractor for
Natural RPC Server. Natural in Command-line
Mode
-extract:pli Extract the PL/I sources from an RPC Using the IDL Extractor for
Extractor Service. PL/I in Command-line Mode

Designer 59
Using EntireX in the Designer Command-line Mode

Command Description Syntax / Examples

-extract:wsdl Extract an IDL file and an XMM file from a Using the IDL Extractor for
Web service. WSDL in Command-line
Mode
-extract:xml Extract an IDL file and an XMM file from an Using the IDL Extractor for
XML Document. XML Document in
Command-line Mode
-extract:xsd Extract an IDL file and an XMM file from an Using the IDL Extractor for
XML Schema. XML Schema in
Command-line Mode
-help List the short description of all commands.
-java:all Generate all Java source files for the specified Using the Java Wrapper in
IDL file(s). Command-line Mode
-java:allbeancompliant Generate all Java source files for the specified
IDL file(s). The client object will be
JavaBean-compliant.
-java:client Generate the Java client(s) for the specified
IDL file(s).
-java:clientbeancompliant Generate the JavaBean-compliant Java
client(s) for the specified IDL file(s).
-java:server Generate the Java server(s) for the specified
IDL file(s).
-java:tester Generate the Java client(s) and tester(s) for
the specified IDL file(s).
-list:natural List the Natural sources or objects from a Using the IDL Extractor for
Natural RPC Server. Natural in Command-line
Mode
-list:pli List the PL/I sources on an RPC Extractor Using the IDL Extractor for
Service. PL/I in Command-line Mode
-map:soap Create SOAP-conformant XML mapping for Using the XML/SOAP
all programs. Wrapper in Command-line
-map:xmlattributes Create attribute-preferred XML mapping for Mode
all programs.
-map:xmlelements Create element-preferred XML mapping for
all programs.
-map:xmlwithxsd Create element-preferred XML mapping with
XML Schema for all programs.
-natural:client Generate Natural RPC client from the Using the Natural Wrapper
specified IDL file. in Command-line Mode
-natural:server Generate Natural RPC server from the
specified IDL file.
-pli:client Generate a PL/I RPC client from the specified Using the PL/I Wrapper in
IDL file. Command-line Mode

60 Designer
 Using EntireX in the Designer Command-line Mode

Command Description Syntax / Examples

-pli:server Generate a PL/I RPC server from the specified
IDL file.
-version Prints the version and exits.
-wsdl Generates WSDL for the specified IDL file(s). Using the Web Services
Wrapper in Command-line
Mode
-xml:sample Create sample XML documents for all Using the XML/SOAP
programs. Wrapper in Command-line
Mode

Designer 61
62
10 EntireX IDL Preferences

■ Defaults for EntireX Wrappers ............................................................................................................ 64

■ Storing IDL Properties in an External File ............................................................................................. 65

63
EntireX IDL Preferences

Defaults for EntireX Wrappers

In the Preferences page you can specify defaults for Broker ID and service description
(class/server/service) that are used in the various EntireX Wrappers.

To specify defaults

■ Start Designer and choose Window > Preferences > Software AG > EntireX.

To overwrite the preferences

■ From the context menu of the IDL file, choose Properties.

You can change the preferences for each IDL file individually.

64 Designer
 EntireX IDL Preferences

Storing IDL Properties in an External File

When archiving an EntireX project with the export feature of Eclipse or the check-in feature of a
revision control system such as Subversion or CVS, you can use an external properties file to store
the properties of your IDL files. These properties are restored from this external file when the
project is imported or checked out.

Note: This feature is not the default behavior and must be enabled for source and target
environment as described below.

To enable the creation of external properties files

1 Start Designer and choose Window > Preferences > Software AG > EntireX and check the
box Use external properties file....
2 Modify the properties of your IDL file. If you make any changes to default values, these
changes will be stored in a properties file with the name <name>.[Link].

When you archive your EntireX project using the Eclipse or a revision control system, make sure
the external properties file is included for every IDL file. When you recreate your EntireX project
in the same or a different environment, the properties of the IDL file are restored from the external
properties file. In the target system, the box Use external properties file... must also be checked.

Designer 65
66