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. See Server Mapping Files for COBOL in the EntireX Workbench documentation. This document covers the following topics:

• Server-side Mapping Files in the RPC Server

• Deploying Server-side Mapping Files to the RPC Server

• Undeploying Server-side Mapping Files from the RPC Server

• Change Management of Server-side Mapping Files

• List Deployed Server-side Mapping Files

• Check if a Server-side Mapping File Revision has been Deployed

• Access Control: Secure Server Mapping File Deployment

• Ensure that Deployed Server-side Mapping Files are not Overwritten

• Is There a Way to Smoothly Introduce Server-side Mapping Files?

See also Source Control of Server Mapping Files | Comparing Server Mapping Files | When is a Server Mapping File Required? | Migrating Server Mapping Files in the EntireX Workbench documentation.

---

Server-side Mapping Files in the RPC Server

Under z/OS, server-side mapping corresponds to lines of EntireX Workbench files with extension .svm. See Server Mapping Files for COBOL. The mapping information is stored as records within one VSAM file, the server-side mapping container. This container contains all server-side mapping entries from all EntireX Workbench files with extension .svm. The unique key of the VSAM file file consists of the first 255 bytes of the record: for the type (1 byte), for the IDL library (127 bytes) and for the IDL program (127 bytes).

If one server requires a server-side mapping file, you need to provide this to the RPC server:

• Development environments: to deploy new server-side mapping files, see Deploying Server-side Mapping Files to the RPC Server.

• Production environments: provide a server-side mapping container (VSAM file) containing all required server-side mapping files to the RPC server. See configuration parameter svm.

If no server requires server-side mapping, you can execute the RPC server without server mapping files:

• Development environments: you can disable the deployment service. See Disabling the Deployment Service.

• Production environments: there is no need to provide a server-side mapping container (VSAM file) to the RPC server. See configuration parameter svm.

Deploying Server-side Mapping Files to the RPC Server

The following approaches are available to deploy a server-side mapping file (EntireX Workbench file with extension .svm; see Server Mapping Files for COBOL):

• Server Mapping Deployment Wizard

• FTP and IDCAMS

To deploy a server-side mapping file with the Server Mapping Deployment Wizard

1. Make sure your RPC server is active and that the Deployment Service of the RPC server is properly configured. See Deployment Service.

2. From the context menu of your IDL file, choose COBOL > Deploy/Synchronize Server Mapping and call the Server Mapping Deployment Wizard. See Server Mapping Deployment Wizard in the EntireX Workbench documentation.

To deploy a server-side mapping file using FTP and IDCAMS

1. Make sure the server-side mapping container (VSAM file) is installed. See Install the Server-side Mapping Container for an IMS RPC Server (Optional) in the z/OS Installation documentation.

2. Allocate a target sequential file on your mainframe.

3. Allow write access to the VSAM file mentioned above and usage of IDCAMS tools.

4. Transfer the server-side mapping file to the target host, using FTP. You have to switch to text mode and the codepage of the FTP service must be the same as the codepage (locale string) of the RPC server used.

5. Install the server mapping contained in the server-side mapping file into the server-side mapping container (VSAM file) with an appropriate IDCAMS job.

   //EXPSVMR  JOB (,,,999),ENTIREX,NOTIFY=&SYSUID,MSGLEVEL=(1,1),
   //             CLASS=K,MSGCLASS=X,REGION=0M,COND=(0,LT)
   //*-----------------------------------------------------* 
   //* FILL THE SVM VSAM CLUSTER                           *
   //*-----------------------------------------------------*
   //IMPORT   EXEC PGM=IDCAMS
   //RECORDS  DD DISP=SHR,DSN=EXP.SVM.TARGET.SEQ.RECORDS
   //SVM      DD DISP=SHR,DSN=EXP.SVM.KSDS
   //SYSPRINT DD SYSOUT=*
   //SYSIN    DD *
     REPRO - 
       REPLACE -
       INFILE(RECORDS) -
       OUTFILE(SVM)

   Note:
   If you omit the keyword REPLACE or define NOREPLACE in the SYSIN data stream of IDCAMS instead, existing server mapping information is not overwritten. This protects server-side mapping records from being overwritten by duplicates.

Undeploying Server-side Mapping Files from the RPC Server

Use the Server Mapping Deployment Wizard to undeploy a server-side mapping file (Workbench file with extension .svm). See Server Mapping Files for COBOL.

To undeploy a server-side mapping file with the Server Mapping Deployment Wizard

1. Make sure your RPC server is active and that the Deployment Service of the RPC server is properly configured. See Deployment Service.

2. Make sure your IDL file is within an EntireX Workbench directory (folder) without the related server-side mapping file (.svm).

3. From the context menu of your IDL file, choose COBOL > Deploy/Synchronize Server Mapping and call the Server Mapping Deployment Wizard. See Server Mapping Deployment Wizard in the EntireX Workbench documentation. Because there is no related server-side mapping file in the Workbench, all server mapping information related to the IDL file in the RPC server will be removed.

Change Management of Server-side Mapping Files

Under z/OS, change management for a VSAM file (server-side mapping container, see Server-side Mapping Files in the RPC Server) is similar to change management for a database. The complete VSAM file can be backed up at any time, for example by using IDCAMS. All updates to the VSAM file done after a backup must be kept.

All EntireX Workbench server-side mapping files (.svm) added since the last backup should be available. See Server Mapping Files for COBOL in the EntireX Workbench documentation.

List Deployed Server-side Mapping Files

Use IDCAMS to list the contents of the server-side mapping container. See Server-side Mapping Files in the RPC Server.

//EXXPRINT JOB (,,,999),ENTIREX,NOTIFY=&SYSUID,MSGLEVEL=(1,1),  
//             CLASS=K,MSGCLASS=X,REGION=0M 
//*-----------------------------------------------------------*
//* PRINT CONTENTS OF AN SVM VSAM CLUSTER                     *
//*-----------------------------------------------------------*
//SVMPRINT EXEC PGM=IDCAMS                                     
//SYSPRINT DD SYSOUT=*                                         
//IN       DD DISP=SHR,DSN=ETS.SVM.KSDS                        
//OUT      DD SYSOUT=*                                         
//SYSIN    DD *                                                
  PRINT  -                                                     
    INFILE(IN) -                                               
    DUMP | HEX | CHAR -                                                     
    OUTFILE(OUT)                                               
/*                                                              
//

Use DUMP or CHAR format to print the server-side mapping records of the VSAM file.

Check if a Server-side Mapping File Revision has been Deployed

Server-side mapping records in the server-side mapping container correspond to lines of EntireX Workbench files with extension .svm. See Server Mapping Files for COBOL in the EntireX Workbench documentation. The records contain a creation timestamp at offset 276 (decimal) in the format YYYYMMDDHHIISST. Precision is 1/10 of a second. The creation timestamp can be checked.

The timestamp can be found on the same offset in the records in the server-side mapping container (VSAM file). See Server-side Mapping Files in the RPC Server.

Access Control: Secure Server Mapping File Deployment

For deployment with the Server Mapping Deployment Wizard, use EntireX Security if the broker is running on platforms z/OS, UNIX , Windows or z/VSE. See Enabling the Deployment Service.

For IBM deployment tool IDCAMS, use RACF to secure deployment.

Ensure that Deployed Server-side Mapping Files are not Overwritten

For IDCAMS, use the NOREPLACE option to disallow overwriting of duplicate server-side mapping records in the server-side mapping container (VSAM file); see Server-side Mapping Files in the RPC Server. See also Deploying Server-side Mapping Files to the RPC Server.

Is There a Way to Smoothly Introduce Server-side Mapping Files?

All EntireX RPC servers can be executed without server-side mapping files. See Server-side Mapping Files in the RPC Server. There is no need to install the server-side mapping container if the following conditions are met:

• You do not use features that require server mapping; see When is a Server Mapping File Required?

• Server-side type of COBOL mapping is switched on in the EntireX Workbench. If you have not used server-side mapping, we recommend you use client-side mapping. See Server Mapping Files for COBOL.

You can also call COBOL servers generated or extracted with previous versions of EntireX mixed with a COBOL server that requires server-side mapping. All EntireX RPC servers are backward compatible.