= Important notes when upgrading to MS4W 5 from MS4W 4 =

[[PageOutline]]

== REQUIREMENTS.txt ==

* always first follow the instructions in the file ''/ms4w/REQUIREMENTS.txt'' to install the updated "Microsoft Visual C++ Redistributable" on your server

== ms4w.conf ==

* as of MS4W 5, you must configure the new ''/ms4w/ms4w.conf'' file, as the !MapServer 8.0 release tightened security for the ''MAP='' parameter
  * Apache and MS4W's commandline tools have been configured to use that config file
* see [https://ms4w.com/README_INSTALL_MS4W_5.html#securing-your-ms4w-installation Securing Your MS4W Installation]
* when [https://ms4w.com/README_INSTALL.html#fastcgi enabling FastCGI], you must also point to ''ms4w.conf'' by setting the ''MAPSERVER_CONFIG_FILE'' variable in your ''httpd.conf'' file, such as:
  {{{
    <IfModule fcgid_module>
      FcgidMinProcessesPerClass 0
      FcgidIdleScanInterval 1
      FcgidProcessLifeTime 10
      FcgidInitialEnv MAPSERVER_CONFIG_FILE "/ms4w/ms4w.conf"
   </IfModule>
  
  }}}
* to enable the Microsoft SQL Server plugin (see [https://ms4w.com/README_INSTALL.html#microsoft-sql-server steps]), you must be sure to add a ''PLUGINS'' section to ''ms4w.conf'', such as:
  {{{
    PLUGINS
      "mssql" "/ms4w/msplugins/mssql/msplugin_mssql2008.dll"
    END 
  }}}

== SWIG !MapScript ==

=== PHP ===

* test PHP !MapScript at the commandline by executing:
  {{{
  setenv.bat
  php -dextension=C:/ms4w/Apache/php/ext/php_mapscript.dll -r "echo msGetVersion();"
  }}}
* as of MS4W 5.0, there is '''no external file to include''' in your PHP scripts (the constants and functions are wrapped inside the !MapScript PHP extension instead)
* see the updated example scripts here on the Wiki, such as:
  * query example: [[SWIGMapScriptQuery|MS4W 5.x]]
  * new layer example (create WMS layer & setting metadata, create polygon layer + opacity, create point layer): [[SWIGMapScriptNewLayer|MS4W 5.x]]
  * WMS wrapper example: [[WMSWrapper|MS4W 5.x]]
  * setOpacity() example: [[SWIGMapScriptOpacity|MS4W 5.x]]
* ''quickmap.php'' has also been updated (see locally at ''/ms4w/Apache/htdocs/quickmap.php'')
* be aware that with the !MapServer 8 release, many '''deprecated''' things have been removed and will now throw an error.  For example, there is no longer a ''setMetaData()'' function for a Layer (or a ''getMetaData()'' function), in [[https://mapserver.org/mapscript/mapscript.html|SWIG MapScript]].  Instead we must access the 'metadata' hashTableObj keys and values directly, here is a working example:
  {{{
    #!php
    <?php
      //set metadata using the new 'metadata' hashTableObj keys and value directly
      $oWMSLayer->metadata->set("wms_name", "popplace");
      $oWMSLayer->metadata->set("wms_title", "Cities");
      $oWMSLayer->metadata->set("wms_srs", "EPSG:3978");
      $oWMSLayer->metadata->set("wms_server_version", "1.1.1");
      $oWMSLayer->metadata->set("wms_format", "image/png");
      //set the PROCESSING directive on the layer (not beneficial for WMS layers, but useful for database layers, so set here only as an example)
      $oDBLayer->setProcessingKey("CLOSE_CONNECTION", "DEFER");
      //get LAYER metadata using the new 'metadata' hashTableObj keys directly
      echo $oWMSLayer->metadata->get("wms_title");
      //get WEB object metadata
      echo $oMap->web->metadata->get("wms_title");
    ?>
  }}}

=== Python ===

* test Python !MapScript at the commandline by executing:
  {{{
  setenv.bat
  python -c "import mapscript; print (mapscript.msGetVersion())"
  }}}
* ''quickmap.py'' has been included in ''/ms4w/msplugins/mapscript/python/'' (follow the instructions at top of file)
* the GDAL Python utilities can be called at the commandline such as:
  {{{
    setenv.bat
    gdal_merge --help
    gdal2tiles --help
  }}}
* test the GDAL Python module at the commandline by executing:
  {{{
    setenv.bat
    python -c "from osgeo import gdal;print(gdal.__version__)"
  }}}
* upgrade pip
  {{{
    setenv.bat
    python -m pip install --upgrade pip
  }}}
== PROJ ==

* Apache's conf & setenv.bat now set the environment variable ''PROJ_DATA'' to PROJ's new location:
  {{{
    \ms4w\share\proj
  }}}
  If your mapfiles set a PROJ_DATA (which is not recommended, as MS4W's Apache does this for you) you will have to update your PROJ_DATA value
* MS4W 5.0 includes PROJ 9, which (since PROJ 8) contains many changes: 
  * since the PROJ 9.1 release, for the former ''PROJ_LIB'' variable has been replaced with ''PROJ_DATA''
  * allowing to dynamically pull in various grids, to improve accuracy
    * see settings in ''/ms4w/share/proj/proj.ini''
    * since we are involved in displaying maps over the internet, we should likely have these grids locally on the server
      * execute the following to install the grids (into /ms4w/share/proj/)
        {{{
          setenv.bat
          proj-install-grids.bat
        }}}
  * all EPSG codes are stored in ''proj.db'', an SQLite database, stored in ''/ms4w/share/proj/'', instead of the former ''epsg'' text file

== Removed Mapfile Parameters ==

The following (formerly deprecated) popular mapfile parameters will now cause errors in your MS4W 5.x mapfile, so you '''MUST REMOVE''' them:

1. '''DUMP TRUE'''

   Instead, you can configure querying of your layer by using METADATA instead, such as:
   {{{
   LAYER
     ...
     METADATA
       "wms_title"         "Populated Places"
       "wms_include_items" "all"
       "gml_include_items" "all"
       "gml_featureid"     "ogc_fid"	
     END #metadata
     ...
   END #layer
   }}}

2. '''OPACITY at the LAYER-level'''

   Instead it must be inside a [[https://mapserver.org/mapfile/composite.html|COMPOSITE]] object:
   {{{
   LAYER
     ...
     COMPOSITE
       OPACITY 40
     END #composite
   END #layer
   }}}

3. '''COLOR at the CLASS-level'''

   Instead it must be inside the class' [[https://mapserver.org/mapfile/style.html|STYLE]] object:
   {{{
   LAYER
     ...
     CLASS
       ...
       STYLE
         COLOR 120 120 120
       END #style
     END #class
   END #layer
   }}}

''see the [[https://mapserver.org/development/rfc/ms-rfc-133.html#proposed-keyword-changes|full list]] of removed parameters

== map2img ==

The former ''shp2img'' commandline utility has been renamed to [https://mapserver.org/utilities/map2img.html map2img].