Compiling and Deploying Maps
This chapter describes how to compile maps by using map source codes to generate symbolic and physical map files. It then explains how and where to deploy the map files.
1. Compiling Maps
Map source codes need to be compiled in order to generate symbolic map files (which are used by the applications) and physical map files (which are used by the OSC application server).
There are two tools that are used for compiling map files: mscasmc and mscmapc.
| Compiling Tool | Description |
|---|---|
Preprocesses assembler macro commands for use in a map file. These macro commands are used during the dump process. |
|
Compiles map source codes to generate symbolic maps (in the form of COBOL copybook files) and physical maps (binaries). |
|
Refer to Creating the Maps of this guide for a map compilation example. |
1.1. mscasmc
The mscasmc tool preprocesses assembler macro commands for use in a map file. Certain macros used such as 'PRINT ON', 'NOGEN', and 'TITLE' don’t affect output but are still used in the dump process. These types of macros must be preprocessed by mscasmc.
Usage
The mscasmc tool can be invoked as follows:
Usage: mscasmc [options] file
| mscasmc -o output_file file
-
[options]
Option Description [-d]
Displays real-time preprocessing output. This option allows the user to observe the process and find the location of an error that might occur during preprocessing.
[-h]
Shows mscasmc help options.
[-v]
Displays mscasmc version information.
-
Input parameters
Parameter Description file
Specifies the map file to be preprocessed.
-o output_file
Specifies the file where mscasmc results will be saved.
Examples
The following example shows how mscasmc is used to preprocess the assembler macro commands for the dump in SCSOW03.map.
$ mscasmc SCSOW03.map
After preprocessing, the following messages will be displayed.
MSCASMC : input map : SCSOW03.map MSCASMC : file[SCSOW03.map.atm] create ok.
1.2. mscmapc
The mscmapc tool generates two files – a symbolic map file and a physical map file – by compiling map source codes.
The symbolic map file is a COBOL copybook file that defines the data structures used in applications. The physical map file is a binary file which describes the properties of each field in the map and the information required for data conversion.
Usage
The mscmapc tool can be invoked as follows:
Usage: mscmapc [options1] file
| mscmapc [options2] dir file
| Option | Description |
|---|---|
[-d] |
Displays real-time preprocessing output. This option allows the user to observe the process and find the location of an error that might occur during preprocessing. |
[-o dir] |
Specifies a directory where the symbolic map and the physical map are created. |
[-p 1|2] |
Offers a preview emulator display screen.
|
[-r region] |
Specifies the name of the region that will generate the symbolic map and the physical map. The physical and symbolic directories should be created first, under a directory specified in MAPDIR key of the GENERAL section in osc.{servername} of the specified region. |
[-s file] |
Creates a file with the file name specified when creating a Symbolic Map file. |
[-h] |
Displays help information for mscmapc. |
[-v] |
Displays version information for mscmapc. |
Examples
The following example demonstrates the generation of the symbolic map file and the physical map file in the current directory after the CESN.map file is compiled.
$ mscmapc CESN.map >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> * input map : CESN.map * Copybook : [./CESN.cpy] create. * binary image : [./CESN.phm] create. <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
The messages at the bottom of the example indicate successful execution.
In the following example, a copybook file and a binary are created in the ~/OPENFRAME_HOME/osc/map directory by setting the –o option.
$ mscmapc -o $OPENFRAME_HOME/osc/map CESN.map >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> * input map : CESN.map * Copybook : [/home/oframe/OpenFrame/osc/map/CESN.cpy] create. * binary image : [/home/oframe/OpenFrame/osc/map/CESN.phm] create. <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
In the next example, the files are generated in the OSC00001 region after compiling the CESN.map file with the -r option.
$ mscmapc -r OSC00001 CESN.map >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> * input map : CESN.map * Copybook : [/home/oframe/OpenFrame/osc/region/OSC00001/map/symbolic/CESN.cpy] create. * binary image [/home/oframe/OpenFrame/osc/region/OSC00001/map/physical/CESN.phm] create. <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
2. Map Deployment
After the symbolic map and physical map are created through the mscmapc tool, they need to be deployed in order to be used by an application or by the OSC application server. The following section describes how to put map files in the appropriate places and enable them to be used in the actual system.
2.1. Symbolic Map Deployment
The symbolic map is a COBOL copybook file that declares the map-related data structures that will be used by an application. Because it is used when application programs are compiled, the symbolic map file must be placed in a copybook directory that the COBOL compiler can access.
The [-o] and [-r] options are used by mscmapc during compilation to determine the storage location of the symbolic map file.
-
If neither [–o] nor [–r] is set:
The symbolic map file is created at the location where mscmapc is executed. The file name will be the map name specified in the map source code, and the .cpy extension will be used for the file. Before the symbolic map can be used, it must be moved to the copybook directory that the COBOL compiler uses. Note that if several map source codes have the same map name and are compiled from the same path, the last symbolic map file that is created will overwrite the previous ones.
-
If either [–o] or [–r] is set:
-
If the [–o] option is set
The symbolic map file will be created at the location specified after [-o]. The file name will be the map name specified in the map source code, and the .cpy extension will be used for the file. Before the symbolic map can be used, it must be moved to the copybook directory that the COBOL compiler uses. Note that if several map source codes have the same map name and are compiled from the same path, the last symbolic map file that is created will overwrite the previous ones.
-
If the [–r] option is set
If the MAPDIR key (located in the GENERAL section of osc.{servername} subject in OpenFrame configuration) has been configured, the symbolic map file will be deployed to the symbolic/(MAPSET_NAME) directory under the MAPDIR directory. If the MAPDIR setting has not been configured, the map file will be deployed, by default, to the $(OPENFRAME_HOME)/osc/region/(REGION_NAME)/map/symbolic directory.
There are two ways to use a symbolic map created with the [-r] option.
-
Using the environment variable
Set the environment variable that specifies where the COBOL compiler must look for symbolic map files. For MF-COBOL, this is the $COBCPY environment variable.
-
Using the option
Set the storage location of the symbolic map files by using the [–f] and [–p] options of osccobprep. Then, the symbolic map files can be preprocessed to be included in the application program source codes.
-
-
|
In addition to the previous methods, users can simply copy the symbolic map files to a predetermined copybook path. However, this is not recommended because map files can still be potentially overwritten (as described previously with the [–o] option). |
2.2. Physical Map Deployment
The physical map files are used by the OSC application server. Some physical map files that are used only by a certain region must be deployed to a specific directory designated for that region.
If the MAPDIR setting (located in the GENERAL section of the OSC region configuration file) is configured, the physical map files will be deployed to the (named physical) directory under the MAPDIR directory. If the MAPDIR setting is not configured, physical map files will be deployed to the $(OPENFRAME_HOME)/osc/region/(REGION_NAME)/map/physical directory. Therefore, to use maps on a system, the location of compiled physical maps must be included in the path.
As for symbolic map files, the location of the physical map varies depending on whether or not the [-o] or [-r] options are used when map source code is compiled with mscmapc.
-
If neither the [–o] nor [–r] options are set:
The physical map file will be created at the location where mscmapc is executed. Before the physical map can be used, it must be moved to the physical map deployment directory of the OSC region that will use the map.
-
If either [–o] or [–r] is set:
-
If the [-o] option is set
The physical map file will be created at the location specified after [-o]. Before the physical map file can be used, the map must be moved to the physical map deployment directory of the OSC region that will use the map.
-
If the [-r] option is set
The physical map file will be created automatically in the physical map deployment directory of the region. The file name will follow the mapset name. Since the physical map files will be deployed at the same time, the files do not need to be moved to another path. To use the files in a different region, copy them to that region’s physical map directory.
-
3. Dynamically Updating Maps
Maps may eventually need to be updated while OSC is running. For this kind of situation, OpenFrame/OSC provides the mscmapupdate tool.
3.1. mscmapupdate
The mscmapupdate tool dynamically manages mapset information used by OSC regions. While tasks are in progress, the user can change map information and promptly apply the changes, or load additional information. The mscmapupdate tool supports functions to search and delete mapset information stored in the current memory.
Usage
The mscmapupdate tool can be invoked as follows:
Usage: mscmapupdate [options] | mscmapupdate region | mscmapupdate region -f filename | mscmapupdate region -l mapset [-n] | mscmapupdate region -r mapset [-n]
-
[options]
Option Description [-h]
Displays help information for mscmapupdate.
[-v]
Displays version information for mscmapupdate.
[-n]
Applies mapset update to all nodes of the specified region.
-
Input parameters
Parameter Description region
Displays mapset information registered in the given OSC region.
-f filename
Specifies a name of a physical mapset file to load into memory. If the same mapset already exists, it is updated.
-l mapset
Specifies a mapset and mapset names to update and load into the OSC region memory. If the same mapset has already been loaded, it is updated.
-r mapset
Releases the mapset in the OSC region.
Examples
The following example displays mapset information registered in the OSC00001 region.
$ mscmapupdate OSC00001 * loaded mapset list 0001 : mapset[CESN] 0002 : mapset[OIVPMS1]
In the following example, the OIVPMS1 mapset is updated in the OSC00001 region. Use the -r option to delete a mapset from a region.
$ mscmapupdate OSC00001 -l OIVPMS1
In the following example, the OIVPMS1 mapset is updated in all nodes of the OSC00001 region. Use the -r option to delete a mapset from a region.
$ mscmapupdate OSC00001 -l OIVPMS1 -n