Upgrading RPG API Express 3.5.x

The upgrade process for RPG API Express is dependent on how many libraries contain RPG API Express objects. You can determine if RPG API Express is installed in multiple libraries with this command:

WRKOBJ OBJ(*ALL/RXS*) OBJTYPE(*SRVPGM)

If the WRKOBJ command lists only library RXS, you should use the upgrade instructions for Single Library Installation below.

If the WRKOBJ command lists libraries other than RXS, please use the upgrade instructions for Multiple Library Installation below.

Additionally, if you have a library named KTLIC on your IBM i, please follow the instructions for KTLIC Library Deprecation below before beginning any upgrade.

Single Library Installation

Note:

  • @@@ is the version number of the source/current version level (example: 220)
  • ### is the version number of the target/new version level (example: 350)
For clarity, you may wish to copy these instructions to a text editor and then perform a scan and replace for the above values before beginning the upgrade.

  1. Unzip the downloaded upgrade file to C:\temp (or the directory of your choice).

  2. Issue the IBM i command:
    CRTSAVF FILE(QGPL/RXS###) AUT(*ALL)

  3. FTP the file rxs.savf from your PC to the IBM i in BINARY mode into the save file that was just created:
    1. Open a DOS prompt (Start Run type 'cmd' and hit Enter)
    2. Type the following into the DOS prompt, replacing the IP address with that of your IBM i:
      ftp 127.0.0.1
    3. When prompted, enter your user profile and password
    4. Execute the following commands in the DOS prompt to transfer the file:
      1. binary
      2. lcd C:\temp
        Note: Replace C:\temp with the location of the rxs.savf on your local computer.
      3. quote site namefmt 0
      4. cd QGPL
      5. put rxs.savf rxs###.savf
      6. quit

  4. End all RPG API Express Apache instances. Note that this will mean your web services are NOT accessible! Execute the following IBM i command to end the Apache instances:
    ENDTCPSVR SERVER(*HTTP) HTTPSVR(RXS)
    Note: Be sure to execute this command for any other Apache instances that also use RPG API Express.

  5. Perform a full backup of library RXS.

  6. Execute the following IBM i commands in sequence to upgrade the library RXS. Please be careful to enter the commands EXACTLY as listed, except for adjusting the SAVF parameter:
    1. RSTOBJ OBJ(*ALL) SAVLIB(RXS) MBROPT(*ALL) ALWOBJDIF(*FILELVL *OWNER) OMITOBJ((RXSUNQ) (RXSCFG) (LICP) (RXSRTRCTL) (RXSRTRLOG) (EXAMPLE)) RSTLIB(RXS) DEV(*SAVF) SAVF(QGPL/RXS###)
      Note: The above RSTOBJ command may report that file RXS was not restored. If this occurs, please rename the existing RXS file to RXS@@@ where @@@ is the pre-upgrade version level. Then retry the RSTOBJ command.
    2. RSTOBJ OBJ(RXSUNQ RXSCFG LICP RXSRTRCTL RXSRTRLOG) SAVLIB(RXS) OPTION(*NEW) RSTLIB(RXS) DEV(*SAVF) SAVF(QGPL/RXS###)
      Note: The above RSTOBJ command may report that no objects were restored. This is not an error condition and you should continue with the next step.
    3. RNMOBJ OBJ(RXS/EXAMPLE) OBJTYPE(*FILE) NEWOBJ(EXAMPLE@@@)
      Note: The above RNMOBJ command may optionally be replaced with DLTF FILE(RXS/EXAMPLE) to delete the EXAMPLE source physical file. You should only do this if you are confident that your company has not stored your own source code inside the EXAMPLE source physical file.
    4. RSTOBJ OBJ(EXAMPLE) OBJTYPE(*FILE) SAVLIB(RXS) MBROPT(*ALL) ALWOBJDIF(*FILELVL *OWNER) RSTLIB(RXS) DEV(*SAVF) SAVF(QGPL/RXS###)

  7. Execute the following IBM i commands when files RXS/RXSRTRCTL and RXS/RXSRTRLOG do NOT already have a RXSRTR member:
    1. RNMM FILE(RXS/RXSRTRCTL) MBR(RXSRTRCTL) NEWMBR(RXSRTR)
    2. RNMM FILE(RXS/RXSRTRLOG) MBR(RXSRTRLOG) NEWMBR(RXSRTR)
    3. CHGPF FILE(RXS/RXSRTRCTL) MAXMBRS(32)
    4. CHGPF FILE(RXS/RXSRTRLOG) MAXMBRS(32)

  8. Execute the following IBM i commands when your pre-upgrade version was previous to version 2.70:
    1. RMVLIBLE LIB(RXS)
    2. ADDLIBLE LIB(RXS) POSITION(*FIRST)
    3. APYLIC LICKEY(<<insert key that was provided during your upgrade planning>>) PRODUCT(RXS)
      Note: If you need a temporary license key, please email our support team at isupport@katointegrations.com.

  9. Restart all RPG API Express Apache instances:
    STRTCPSVR SERVER(*HTTP) HTTPSVR(RXS)
    Note: Be sure to also execute this command for any custom Apache instances that also use RPG API Express.

  10. Initialize RXS Router:
    INZRXSRTR ENV(*ALL)

Multiple Library Installation

If you haven't yet, run the following command:
WRKOBJ OBJ(*ALL/RXS*) OBJTYPE(*SRVPGM)

Using the libraries output by the WRKOBJ command, please make a list of the libraries which need to be upgraded, but do not include the library RXS on the list. There should be an Apache instance for each library and the instance name should be the same as the library. As you continue with these instructions, this list will be referred to as the "Upgrade List". These instructions will have you first perform the upgrade to your RXS library, then to each library on the Upgrade List.

These instructions will reference the library and Apache instance named MYRXS. You may or may not have a MYRXS library and Apache instance on your Upgrade List. Regardless, when upgrading each library on your Upgrade List, substitute that library's name in place of MYRXS in the following instructions.

Note:

  • @@@ is the version number of the source/current version level (example: 220)
  • ### is the version number of the target/new version level (example: 350)
For clarity, you may wish to copy these instructions to a text editor and then perform a scan and replace for the above values before beginning the upgrade.

  1. Unzip the downloaded upgrade file to C:\temp (or the directory of your choice).

  2. Issue the IBM i command:
    CRTSAVF FILE(QGPL/RXS###) AUT(*ALL)

  3. FTP the file rxs.savf from your PC to the IBM i in BINARY mode into the save file that was just created:
    1. Open a DOS prompt (Start Run type 'cmd' and hit Enter)
    2. Type the following into the DOS prompt, replacing the IP address with that of your IBM i:
      ftp 127.0.0.1
    3. When prompted, enter your user profile and password
    4. Execute the following commands in the DOS prompt to transfer the file:
      1. binary
      2. lcd C:\temp
        Note: Replace C:\temp with the location of the rxs.savf on your local computer.
      3. quote site namefmt 0
      4. cd QGPL
      5. put rxs.savf rxs###.savf
      6. quit

  4. End all RPG API Express Apache instances. Note that this will mean your web services are NOT accessible! Execute the following IBM i command to end the Apache instances, while substituting the instance names from the Upgrade List for MYRXS:
    ENDTCPSVR SERVER(*HTTP) HTTPSVR(RXS)
    Note: Be sure to execute this command for any other Apache instances that also use RPG API Express.

  5. Perform full backups of library RXS and all libraries on the Upgrade List.

  6. Execute the following IBM i commands in sequence to upgrade the library RXS. Please be careful to enter the commands EXACTLY as listed, except for adjusting the SAVF parameter:
    1. RSTOBJ OBJ(*ALL) SAVLIB(RXS) MBROPT(*ALL) ALWOBJDIF(*FILELVL *OWNER) OMITOBJ((RXSUNQ) (RXSCFG) (LICP) (RXSRTRCTL) (RXSRTRLOG) (EXAMPLE)) RSTLIB(RXS) DEV(*SAVF) SAVF(QGPL/RXS###)
      Note: The above RSTOBJ command may report that file RXS was not restored. If this occurs, please rename the existing RXS file to RXS@@@ where @@@ is the pre-upgrade version level. Then retry the RSTOBJ command.
    2. RSTOBJ OBJ(RXSUNQ RXSCFG LICP RXSRTRCTL RXSRTRLOG) SAVLIB(RXS) OPTION(*NEW) RSTLIB(RXS) DEV(*SAVF) SAVF(QGPL/RXS###)
      Note: The above RSTOBJ command may report that no objects were restored. This is not an error condition and you should continue with the next step.
    3. RNMOBJ OBJ(RXS/EXAMPLE) OBJTYPE(*FILE) NEWOBJ(EXAMPLE@@@)
      Note: The above RNMOBJ command may optionally be replaced with DLTF FILE(RXS/EXAMPLE) to delete the EXAMPLE source physical file. You should only do this if you are confident that your company has not stored your own source code inside the EXAMPLE source physical file.
    4. RSTOBJ OBJ(EXAMPLE) OBJTYPE(*FILE) SAVLIB(RXS) MBROPT(*ALL) ALWOBJDIF(*FILELVL *OWNER) RSTLIB(RXS) DEV(*SAVF) SAVF(QGPL/RXS###)

  7. Execute the following IBM i commands when file RXS/RXSRTRCTL does NOT already exist:
    RSTOBJ OBJ(RXSRTRCTL RXSRTRLOG) SAVLIB(RXS) DEV(*SAVF) SAVF(QGPL/RXS###) RSTLIB(RXS)

  8. Execute the following IBM i commands when files RXS/RXSRTRCTL and RXS/RXSRTRLOG do NOT already have a RXSRTR member:
    1. RNMM FILE(RXS/RXSRTRCTL) MBR(RXSRTRCTL) NEWMBR(RXSRTR)
    2. RNMM FILE(RXS/RXSRTRLOG) MBR(RXSRTRLOG) NEWMBR(RXSRTR)
    3. CHGPF FILE(RXS/RXSRTRCTL) MAXMBRS(32)
    4. CHGPF FILE(RXS/RXSRTRLOG) MAXMBRS(32)

  9. Execute the following IBM i commands when your pre-upgrade version was previous to version 2.70:
    1. RMVLIBLE LIB(RXS)
    2. ADDLIBLE LIB(RXS) POSITION(*FIRST)
    3. APYLIC LICKEY(<<insert key that was provided during your upgrade planning>>) PRODUCT(RXS)
      Note: If you need a temporary license key, please email our support team at isupport@katointegrations.com.

  10. Execute the following IBM i commands once for each library in the Upgrade List, replacing MYRXS in each command with a library name from the Upgrade List:
    1. Note: The following string is a single command - you must copy the entire string. You may need use the extended command line accessed via STRPDM.
      RSTOBJ OBJ(*ALL) SAVLIB(RXS) MBROPT(*ALL) ALWOBJDIF(*FILELVL *OWNER) OMITOBJ((RXSUNQ) (RXSCFG) (LICP) (INSTALL) (NEWENV) (DSPMCH*) (DSPLIC) (RXSRTRCTL) (RXSRTRLOG) (RXSURI*) (DSPVER) (VER*) (RXSMENU*) (HTTP*) (INZ*) (WRK*) (CRT*) (DLT*) (*ALL *PNLGRP)) RSTLIB(MYRXS) DEV(*SAVF) SAVF(QGPL/RXS###)
      Note: The above RSTOBJ command may report that file RXS was not restored. If this occurs, please rename the existing RXS file to RXS@@@ where @@@ is the pre-upgrade version level. Then retry the RSTOBJ command.
    2. CPYF FROMFILE(RXS/LICP) TOFILE(MYRXS/LICP) MBROPT(*REPLACE) CRTFILE(*YES)
    3. RNMOBJ OBJ(MYRXS/EXAMPLE) OBJTYPE(*FILE) NEWOBJ(EXAMPLE@@@)
      Note: The above RNMOBJ command may optionally be replaced with DLTF FILE(MYRXS/EXAMPLE) to delete the EXAMPLE source physical file. You should only do this if you are confident that your company has not stored your own source code inside the EXAMPLE source physical file.
    4. RSTOBJ OBJ(EXAMPLE) OBJTYPE(*FILE) SAVLIB(RXS) MBROPT(*ALL) ALWOBJDIF(*FILELVL *OWNER) RSTLIB(MYRXS) DEV(*SAVF) SAVF(QGPL/RXS###)

  11. Restart all RPG API Express Apache server instances by executing the following command, replacing MYRXS with a library name from the Upgrade List:
    STRTCPSVR SERVER(*HTTP) HTTPSVR(MYRXS)
    Note: Be sure to execute this command for each instance name on the Upgrade List and for any custom instances that also use RPG API Express.

  12. Initialize RXS Router:
    INZRXSRTR ENV(*ALL)

KTLIC Library Depreciation

Library KTLIC was installed with version level 2.7x only and has been deprecated since version 2.80. KTLIC is no longer needed after upgrading to version 2.80 or higher. If your pre-upgrade version level is already 2.80 or higher, do not run the CPYF command below and instead note the reference to saving and deleting KTLIC.

If your pre-upgrade version is 2.7x, execute the following IBM i commands before beginning any upgrade:

CPYF FROMFILE(KTLIC/LICP) TOFILE(RXS/LICP) MBROPT(*REPLACE) CRTFILE(*YES)

After your upgrade to a version 2.80 or greater is complete and proven successful, please save and then delete library KTLIC.