Creating the mqweb server

If you installed the IBM® MQ for z/OS® UNIX System Services Web Components, and want to use the MQ Console, or the REST API, you need to create and customize the mqweb server.

Before you begin

Before running the crtmqweb script to create the mqweb server, you must set the JAVA_HOME environment variable to reference a 64 bit version of Java on your system.

You need to create the SYSTEM.REST.REPLY.QUEUE in order to use the Liberty server. Do this by using the latest CSQ4INSG sample in Customize the initialization input data sets.

Attention: When starting the mqweb server, if you encounter error message CWWKG0014E, as displayed in the following output:

     Launching mqweb (MQM MVS/ESA V9 R2.0/wlp...) (en_US)
              ÝAUDIT   ¨ CWWKE0001I: The server mqweb has been launched.                     
              ÝWARNING ¨ CWWKF0009W: The server has not been configured to install any features.
              ÝAUDIT   ¨ CWWKF0011I: The mqweb server is ready to run a smarter planet. The mqweb server started in 6.348 seconds.
              ÝERROR   ¨ CWWKG0014E: The configuration parser detected an XML syntax error while parsing the root of the configuration and the referenced configuration documents. 
                              Error: An invalid XML character (Unicode: 0x4c) was found in the prolog of the document. 
                               File: file:<your filepath>/servers/mqweb/server.xml Line: 1 Column: 1

you should check the z/OS setting of AUTOCVT (automatically convert files from one code set to another) and adjust the value as required by doing one of the following.

In a USS terminal:: Issue the command: echo $_BPXK_AUTOCVT to display the value of this environment variable. If the environment variable is not defined, no value is displayed.; To set the environment variable, see _BPXK environment variables.
System wide:: Example 6 at Displaying status of z/OS UNIX System Services (OMVS) shows how to display the value of the system wide AUTOCVT statement in BPXPRMxx.; To set the environment variable system wide, use the AUTOCVT statement in BPXPRMxx.

If environment variable _BPXX_AUTOCVT is set in a USS terminal, it overrides the system wide setting of statement AUTOCVT in BPXPRMxx.

About this task

You need to perform this task once for each z/OS system where you want to run the MQ Console or REST API.
You need an mqweb server for each version of IBM MQ that is running. For example, if you are running IBM MQ 9.2.0, 9.1.5 and 9.1.0, you need three different mqweb servers.
You might need to refresh or modify the server configuration when migrating from a previous version.

The MQ Console and REST API require the creation of a single Liberty server, called mqweb.

The server configuration and log files are all stored under the Liberty user directory.

The mqweb server needs to be configured with a product ID (PID) that it will run under. This is decided at creation time, and must be the same PID that is to be used to run the local queue managers that the mqweb server connects to.

Note: If local queue managers run under multiple different PIDs, choose one of them to run the mqweb server under.

[MQ 9.2.0 Jul 2020] See Product usage recording with IBM MQ for z/OS products for more information on PIDs and how they are used on z/OS.

[MQ 9.2.0 Jul 2020] It is possible to change the PID that the mqweb server runs under, after it is created, using the setmqweb command.

Carry out the following procedure to create the mqweb server:

Procedure

Decide which PID the mqweb server will run under.
Choose a suitable location for the Liberty user directory.
The user ID that the mqweb server runs under, needs read and write access to this user directory and its contents. As this user directory will contain log files, as well as the server configuration, you should create this directory in a separate file system.
Note: There is a significant amount of disk I/O when the mqweb server starts. To reduce the time taken to start the mqweb server, ensure that both the IBM MQ installation z/OS UNIX file system and the Liberty user directory file system, are either sysplex-aware, or locally mounted on the system where the mqweb server is running.
In z/OS UNIX System Services, ensure that your current directory is PathPrefix/web/bin, by issuing the following command:
```
cd PathPrefix/web/bin
```
PathPrefix is the IBM MQ for z/OS UNIX System Services Components installation path.
Create the Liberty user directory, containing the template mqweb server definition, by running the crtmqweb script.
The format of the crtmqweb command is:
```
crtmqweb user_directory -p pid_value 
```
where:
user_directory

Is the optional Liberty user directory decided in step 2. If this argument is not provided then a default Liberty user directory of /var/mqm/web/installation1 is used.

pid_value
Indicates the PID that the mqweb server will run under. This depends on the PID you decided on in step 1.
If you chose IBM MQ for z/OS (5655-MQ9) then pid_value is MQ.

If you chose IBM MQ for z/OS Value Unit Edition (VUE) (5655-VU9) then pid_value is VUE.

If you chose IBM MQ Advanced for z/OS VUE (5655-AV1) then pid_value is ADVANCEDVUE.
For example, to create the mqweb server with a Liberty user directory of /usr/mqweb and a PID of IBM MQ Advanced for z/OS VUE (5655-AV1) run the following command:
./crtmqweb /usr/mqweb -p ADVANCEDVUE
Change the ownership of the directories and files in the Liberty user directory, so that they belong to the user ID and group that the mqweb server runs under, using the command:
```
chown -R userid:group path
```
To give the group write access to the path, issue the command:
```
chmod -R 770 path
```

What to do next

Creating a procedure for the mqweb server