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 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.
There are client-side mapping files (EntireX Workbench files with extension .cvm) and server-side mapping files
(Workbench files with extension .svm).
If you have not used server-side mapping, we recommend you use client-side mapping.
This document describes the handling of server mapping files (EntireX Workbench files with extension .cvm or .svm) for COBOL and covers the following topics:
See also Server-side Mapping Files in the RPC server documentation for z/OS (CICS, Batch, IMS) | Micro Focus | CICS ECI | IMS Connect | BS2000/OSD | z/VSE (CICS, Batch).
This section covers the following topics:
The following rules apply to a server mapping file for COBOL in the EntireX Workbench:
The mapping file is of type client-side or server-side. Use one type or the other; they cannot be combined. See How to Set the Type of Server Mapping Files.
Mapping files have the extension .cvm or .svm.
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 following rules apply to client-side mapping:
Client-side mapping files have the extension .cvm in the EntireX Workbench.
The mapping files are generated when the EntireX Workbench is in client-side mapping mode, see How to Set the Type of Server Mapping Files.
Handling of client-side mapping is easier than server-side mapping. 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
The mapping is wrapped into the client interface objects when an RPC client is generated. The client-side mapping must available before you creating any RPC client component, that is, the COBOL server program must be extracted or generated first.
The mapping is sent during runtime to the target RPC server with the RPC request.
Only point-to-point connections are allowed. The RPC client with the client-side mapping in its client interface object can only call one specific target COBOL server program. If you want to replace the COBOL server program by another implementation, for example Java, you need to rebuild all the RPC clients without the client-side mapping wrapped into their client interface object.
The following rules apply to server-side mapping:
Server-side mapping files have the extension .svm in the EntireX Workbench.
The files are generated when the workbench is in server-side mapping mode, see How to Set the Type of Server Mapping Files.
The files have to be deployed to the RPC server. See Deploying Server-side Mapping Files to the RPC Server in the RPC server documentation for z/OS (CICS, Batch, IMS) | Micro Focus | CICS ECI | IMS Connect | BS2000/OSD | z/VSE (CICS | Batch).
Note:
For IMS Connect and CICS ECI connections with the webMethods EntireX Adapter for Integration Server,
server-side mapping files are not deployed. They are wrapped into the Integration Server connection - the same as client-side
mapping files.
For RPC connections, the server-side mapping files must be deployed to the target RPC server.
See the EntireX Adapter documentation under http://documentation.softwareag.com > webMethods Product Line.
Server-side mapping is read at runtime by the RPC server from the server-side mapping container, see Server-side Mapping Files in the RPC Server in the RPC server documentation for z/OS (CICS, Batch, IMS) | Micro Focus | CICS ECI | IMS Connect | BS2000/OSD | z/VSE (CICS, Batch)
Flexible connections are possible: the RPC client can call any target server program as long as the IDL interface matches. You do not need to rebuild the RPC clients when replacing the COBOL server program by a different implementation, for example Java, as required with client-side mapping files.
Server-side mapping files can be migrated to client-side mapping files, see Migrating Server Mapping Files.
Every EntireX Workbench (Eclipse) workspace is either in client-side mapping mode (generating EntireX Workbench server mapping files with extension .cvm) or server-side mapping mode (generating workbench server mapping files with extension .svm) for COBOL mapping. If this decision has not yet been taken for a workspace and the COBOL Wrapper | Extractor is called, you are prompted with the following pop-up to choose the type for COBOL mapping:
For more information on handling the different types of COBOL mapping, see Server Mapping Files in the EntireX Workbench.
In client-side mapping mode, it is not possible to modify server-side mapping files (EntireX Workbench files with extension .svm). This means that if there is a related server-side mapping file available for an IDL file, you cannot use the
IDL Extractor for COBOL to extract an additional interface or modify an existing one
COBOL Wrapper to generate an RPC Server
You have to migrate the server-side mapping files first. See Migrating Server Mapping Files.
In server-side mapping mode, it is not possible to modify client-side mapping files (EntireX Workbench files with extension .cvm). This means that if there is a related client-side mapping file available for an IDL file, you cannot use the
IDL Extractor for COBOL to extract an additional interface or modify an existing one
COBOL Wrapper to generate an RPC Server
Later on, you can readjust the mode in the Preferences of the respective tool. See IDL Extractor for COBOL Preferences or Generation Settings - Preferences in the COBOL Wrapper documentation.
A server mapping file (workbench file with extension .cvm or .svm) 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. The type of server mapping (server-side with extension .svm or client-side with extension .cvm) is defined in a preference that applies to the entire EntireX Workbench (Eclipse) workspace. See How to Set the Type of Server Mapping Files.
| Interface Type | COBOL Syntax | COBOL Mapping Editor | Server Mapping Required |
More Information |
|---|---|---|---|---|
| CICS DFHCOMMAREA and In different to Out | all | yes | CICS with DFHCOMMAREA Calling Convention - In different to Out under COBOL Mapping Editor in the IDL Extractor for COBOL documentation (1) and the following COBOL server examples for CICS input message different to the CICS output message:
|
|
| CICS Channel Container | all | yes | CICS with Channel Container Calling Convention | |
| CICS Large Buffer | all | yes | CICS with DFHCOMMAREA Large Buffer Interface |
|
| IMS MPP (IMS Connect) | all | yes | IMS MPP Message Interface (IMS Connect) | |
| IMS BMP | all | yes | IMS BMP with Standard Linkage Calling Convention | |
| Micro Focus | BINARY clause
|
yes | Micro Focus with Standard Linkage Calling Convention | |
| CICS Channel Container, CICS Large Buffer, IMS MPP (IMS Connect) | OCCURS clause
|
Set Arrays (Fixed <-> Unbounded) | yes | Tables with Fixed Size and example COBOL Server Using Data Length to Process a Variable Number of Array Elements for CICS Channel Container) | CICS Large Buffer (Same | Different) (1) | IMS MPP (IMS Connect). |
| all | OCCURS DEPENDING ON clause
|
yes | Tables with Variable Size - DEPENDING ON Clause under COBOL to IDL Mapping in the IDL Extractor for COBOL documentation
|
|
| all | REDEFINES clause
|
yes | REDEFINE Clause |
|
| all | TRAILING [SEPARATE] clause
|
yes | SIGN LEADING and TRAILING SEPARATE Clause |
|
| all | LEADING [SEPARATE] clause
|
yes | SIGN LEADING and TRAILING SEPARATE Clause |
|
| all | ALIGNED RIGHT attribute
|
yes | ||
| all | all | Rename of program, Set to constant | yes | COBOL Mapping Editor and example COBOL Server with Multiple Functions for CICS Channel Container | CICS Large Buffer (Same | Different) (1) | IMS MPP (IMS Connect) | IMS BMP | Batch | Micro Focus. |
| all | all | Suppress | yes | COBOL Mapping Editor |
| other combinations | no | |||
Notes:
A server mapping file (EntireX Workbench file with extension .cvm or .svm) is generated by the COBOL Wrapper if an RPC server is generated (1) and at least one IDL program meets the criteria in the table below. The type of server mapping (server-side with extension .svm or client-side with extension .cvm) is defined in a preference that applies to the entire EntireX Workbench (Eclipse) workspace. See How to Set the Type of Server Mapping Files.
| Interface Type | IDL Type | COBOL Wrapper | Server Mapping Required |
More Information |
|---|---|---|---|---|
| CICS Large Buffer | all | yes | CICS with DFHCOMMAREA Large Buffer Interface under COBOL Server Interface Types in the COBOL Wrapper documentation
|
|
| CICS Channel Container | all | yes | CICS with Channel Container Calling Convention | |
| IMS BMP | all | yes | IMS BMP with Standard Linkage Calling Convention | |
| Micro Focus | I2 or I4 | yes | Micro Focus with Standard Linkage Calling Convention | IDL Data Types | |
| all | IDL unbounded array | yes | array-definition under Software AG IDL Grammar in the IDL Editor documentation
|
|
| all | IDL unbounded group | yes | group-parameter-definition |
|
| all | all | IDL program name is not a valid COBOL name and is therefore adapted, or the COBOL program name is customized | yes | Customize Automatically Generated Server Names under Generating COBOL Source Files from Software AG IDL Files in the COBOL Wrapper documentation |
| other combinations | no | |||
| (1) | Server mapping files are never generated for RPC clients. |
This section covers the following topics:
Server-side mapping files (EntireX Workbench files with extension .svm) can be migrated to client-side mapping files (EntireX Workbench files with extension .cvm).
Note:
Client-side mapping files are not supported by RPC clients generated with the DCOM Wrapper and COBOL Wrapper.
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, Micro Focus)
the webMethods EntireX Adapter. See EntireX Adapter documentation under http://documentation.softwareag.com > webMethods Product Line
the RPC client runtimes
Rename the extension .svm to .cvm in the EntireX Workbench. This results in a client-side mapping file.
Remove the server-side mapping files in the server-side mapping container of the target RPC server. See Undeploying Server-side Mapping Files to the RPC Server in the RPC server documentation for z/OS (CICS, Batch, IMS) | Micro Focus | CICS ECI | IMS Connect.
Note:
For IMS Connect and CICS ECI connections with webMethods EntireX Adapter for Integration Server, this step is not required.
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.
Test the RPC clients with client-side mapping files.
If necessary, re-deploy the RPC clients with client-side mapping files.
| (1) | This includes all variants of RPC connections of the webMethods EntireX Adapter. See webMethods Integration Server Wrapper. |
Because server mapping files (EntireX Workbench files with extension .cvm or .svm) 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.
For server mapping files (EntireX Workbench files with extension .cvm or .svm), 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.
