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 (Designer 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.

This document describes the handling of server mapping files (Designer files with extension .cvm) for COBOL and covers the following topics:

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.

graphics/svm-cob_scope_client.png

When is a Server Mapping File Required?

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.

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
COBOL Converter and In different to Out all   yes COBOL Converter (2)
IMS MPP (IMS Connect) all   yes IMS MPP Message Interface (IMS Connect)
IMS BMP all   yes IMS BMP with Standard Linkage Calling Convention
CICS DFHCOMMAREA, CICS Channel Container, CICS Large Buffer, IMS MPP (IMS Connect), COBOL Converter OCCURS clause, see COBOL Tables with Fixed Size Set Arrays (Fixed <-> Unbounded) yes See Set Arrays (Fixed <-> Unbounded) for interface type DFHCOMMAREA (In same as Out, In different to Out) | Large Buffer (In same as Out, In different to Out) | Channel Container | IMS Connect | COBOL Converter (In same as Out, In different to Out) (1, 2)
all OCCURS clause, see COBOL Tables with Fixed Size Map to no See Map to for interface type 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, Out, InOut See Map to In, Out, InOut for interface type DFHCOMMAREA (In same as Out) | Large Buffer (In same as Out) | Batch | IMS BMP | In same as Out) (1,2)
CICS DFHCOMMAREA, CICS Channel Container, CICS Large Buffer, IMS MPP (IMS Connect), COBOL Converter COBOL group data items used in optional manner, see Optional COBOL Group Data Items Set multiple possible output structures (MPO) yes See Set Multiple Possible Output (MPO) Structures for interface type DFHCOMMAREA (In same as Out, In different to Out) | Large Buffer (In same as Out, In different to Out) | Channel Container | IMS Connect | COBOL Converter (In same as Out, In different to Out) (1,2)
all COBOL group data items Map to no See Map to for interface type 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, Out, InOut See Map to In, Out, InOut for interface type DFHCOMMAREA (In same as Out) | Large Buffer (In same as Out) | Batch | IMS BMP | In same as Out) (1,2)
all OCCURS DEPENDING ON clause, see COBOL Tables with Variable Size - DEPENDING ON Clause Map to yes See Map OCCURS DEPENDING ON for interface type 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, Out, InOut See Map OCCURS DEPENDING ON for interface type DFHCOMMAREA (In same as Out) | Large Buffer (In same as Out) | Batch | IMS BMP | In same as Out) (1,2)
CICS DFHCOMMAREA, CICS Channel Container, CICS Large Buffer, IMS MPP (IMS Connect), COBOL Converter REDEFINES clause, see REDEFINES Clause Set multiple possible output (MPO) structures yes Set Multiple Possible Output (MPO) Structures for interface type DFHCOMMAREA (In same as Out, In different to Out) | Large Buffer (In same as Out, In different to Out) | Channel Container | IMS Connect (1,2)
Map to COBOL REDEFINES can be used in several ways:
Map to In, Out, InOut COBOL REDEFINES can be used in several ways:
Batch, IMS BMP REDEFINES clause, see REDEFINES Clause Map to In, Out, InOut yes COBOL REDEFINES can be used in serveral ways:

  • Select REDEFINE Paths for interface type Batch | IMS BMP

  • Map to Multiple IDL Interfaces for interface type Batch | IMS BMP
all SIGN LEADING [SEPARATE] clause, see SIGN LEADING and TRAILING SEPARATE Clauses   yes  
all SIGN TRAILING [SEPARATE] clause, see SIGN LEADING and TRAILING SEPARATE Clauses   yes  
all SYNCHRONIZED clause, see SYNCHRONIZED Clause   yes  
all all Rename of program yes See Map to Multiple IDL Interfaces for interface 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 Set to constant yes See Set COBOL Data Items to Constants for interface 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 See Unneeded COBOL Data Items Suppress yes Suppress Unneeded COBOL Data Items for interface 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)
other combinations no  

Notes:

  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.

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

Migrating Server Mapping Files

This section covers the following topics:

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 recommend 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:

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

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.