Install

R6 Interface Setup

Sections in this article

(A) New User ID

  • Add a new user to your iSeries named ‘K3SWEB’
  • Make sure the initial menu is *SIGNOFF
  • The user NEEDS to be enabled
  • Have the password update turned off (set to *NOMAX)
  • Use your discretion when creating the password; but send this to K3S as it is needed for zend server installation
  • K3SWEB user needs *USE authority to object QPMLPMGT in library QSYS
  • K3SWEB user needs *USE authority to commands ADDRPYLE and RMVRPYLE

(B) Zend server installation

Check the Zend server prerequisites here:

K3S will put a save file on your server called ZENDPHP7. When you are ready to insall Zend Server, run the following command while signed on as QSECOFR:

RSTLICPGM LICPGM(7PHPZEND) DEV(*SAVF) SAVF(QGPL/ZENDPHP7)

(C) Setup Zend Server for R6

There will be additional lines added to the main configuration file (/www/zendphp7/conf/httpd.conf) that are used by R6 setup.

Use your favorite editor to go to /www/zendphp7/conf/http.conf (make a backup) and add these lines:

  • At the top
# This will add compression to deliver the web pages and speed up the site 

LoadModule deflate_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
AddOutputFilterByType DEFLATE application/x-httpd-php application/json text/css application/x-javascript application/javascript text/html
  • Find the middle of the document and adjust these settings (some already there, some missing)
DirectoryIndex index.php index.html
TimeOut 30000
KeepAlive On 
KeepAliveTimeout 30
HotBackup Off
  • Add this to the section with all the other Directory entries. This will say how to handle the K3S app
<Directory /usr/local/k3s/k3sapps>
  Options FollowSymLinks
  order allow,deny
  allow from all
  AllowOverride all
</Directory>
  • Where you see the IncludeOptional entries for globals and vhost within the zendphpy structure, add the third line. This says where to find our K3S app
IncludeOptional /usr/local/zendphp7/etc/sites.d/globals-*.conf
IncludeOptional /usr/local/zendphp7/etc/sites.d/vhost_*.conf
## Add this line below
IncludeOptional /usr/local/k3s/siteconfig/vhost_*.conf

Once all added, restart Zend Server. If it was successful, you should see it come back up under wrkactjob

(D) Create App Install Of R6

After setting up Zend Server, we need to create the application install itself. This work will be done on the IFS. You will need to know your three letter library prefix used for your K3S install. Usually for on promise this is ‘K3S’, but can be anything. This example will assume ‘EXT’ for clarity in instructions.

The easiest way to do this is to SSH into the IBM i ( How to start SSH on the IBM i ) and follow the commands below:

1) Create directory for session files

cd /tmp
mkdir k3ssessions
mkdir ext
chmod 777 ext

2) Create main directory structure

cd /usr/local
mkdir k3s
cd k3s
mkdir siteconfig
mkdir versions
mkdir k3sapps 
cd /usr/local/k3s/k3sapps
# Here we make the directory for our application name. Notice it is ext from earlier
mkdir ext 
cd ext
mkdir localphp
# this will give the web user QTMHHTTP access to all the files to server the application
chown -R QTMHHTTP /usr/local/k3s

3) Setup site configuration for Apache

Create (and edit if needed) this file below, and put into /usr/local/k3s/siteconfig. Once inside that directory, restart the zendphp7 Apache instance. If it comes back up, your site is active. The name of this file is based on the 3 character prefix, the ip address of the server, and the port the file should exist at

File: vhost_ext_192.168.0.1_9091.conf
Listen 9091 # This is the port we will listen to for the application

<VirtualHost *:9091> # Same port as listed above

    DocumentRoot "/usr/local/k3s/k3sapps/ext/active" # This is where our active application lives. Notice ext

    <Directory "/usr/local/k3s/k3sapps/ext/active"> # this is where our active application lives. Notice ext
      Options FollowSymLinks
      DirectoryIndex index.php
      AllowOverride All
      Order allow,deny
      Allow from all
      <IfModule mod_authz_core.c>
      Require all granted
      </IfModule>
    </Directory>

    RewriteEngine Off

    <location />
        RewriteEngine On
        RewriteCond %{REQUEST_FILENAME} -s [OR]
        RewriteCond %{REQUEST_FILENAME} -l [OR]
        RewriteCond %{REQUEST_FILENAME} -d
        RewriteRule ^.*$ - [L]
        RewriteCond %{REQUEST_URI}::$1 ^(/.+)/(.*)::\2$
        RewriteRule ^(.*) - [E=BASE:%1]
        RewriteRule ^(.*)$ %{ENV:BASE}/index.php [L]
    </location>

    ExpiresActive On
    ExpiresByType image/png "access plus 1 day"
    ExpiresByType text/css "access plus 1 day"
    ExpiresByType text/x-javascript "access plus 1 day"
    ExpiresByType image/x-icon "access plus 1 day"
    ExpiresDefault "access plus 1 day"
</VirtualHost>

4) Setup the R6 Application itself

We now have all our directory structure setup to handle the R6 application. We need to install the setup files needed into the newly created localphp directory. This is used to deploy every time we update the application.

The three files needed are: k3sbase.local.php db.local.php .user.ini

Note that .user.ini (and all leading file names with a .) is often hidden on a filesystem by default

File: k3sbase.local.php
<?php 
/* 
 * Here is all the local setup information for the K3S R6 install
 */ 
return array ( 
		'k3s_settings' => array ( 
				'slacktoken' => '', # Retrieve your slack token from K3S 
				'api' => 'rpg',     # This is the only API verison offered currently
				'lang' => 'eng',    # Default language
				'application' => 'Replenish', # this is either replenish or restore
				'session_length' => '10080', # How long you can be inactive before needing to login again
				'k3sobj' => 'EXT_5OBJ', # Library that contains the APIs. Notice the example EXT library prefix 
				'erp' => 'ERP', # Name of the ERP we are interfacing with. This is a display feature
				'comp' => 'C', # Located in K_COMPANY.CP_COMP
				'compcod' => 'ABC', # Located in K_COMPANY.CP_COMPCOD
				'logo' => '', # Option to add the customer logo in the top left
		), 
		        'smtp' => array ( # This is the setup info for email
				'name' => 'sherlock.k3s.com', # The domain name of the email server
				'host' => '10.5.49.15', # IP address of the email server
				'port' => '25', # Most likely port 25 unless otherwise notied
				'emailfrom' => 'support@k3s.com', # What FROM address for emails
		) 
);
File: db.local.php
<?php 
/*  
 * Here is all the local database information for the K3S R6 Install
 */ 
return array ( 
	'db' => array ( 
		'driver' => 'IbmDb2', # The driver used to access the IBM i database from PHP
		'db' => '*LOCAL', # This is if we are accessing the database from a different server than the UI, or locally. 
		'persistent' => true, # This can be disabled, but slows down the application tremendously
		'username' => 'username', # This is the user created in Step A
		'password' => 'password', # This is the password created in Step A
		'driver_options' => array ( 
			'i5_naming' => DB2_I5_NAMING_ON, # This allows PHP to understand the IBM i naming scheme 
			'i5_libl' => 'QTEMP QGPL EXT_5DEV EXT_5MOD EXT_5DTA EXT_5OBJ EXT_5WEB MMAIL' # This is the library list for the application setup. this will be custom depending on what libraries are needed for PO approval
		) 
	) 
);
File: .user.ini
 session.save_path = "/tmp/k3ssessions/ext"

5) Get deployment.php and DEPLOYMENT.CLLE files from K3S

These files are the final step to pull and retrieve the latest version of R6. DEPLOYMENT.CLLE will go in your EXT_5MOD library. deployment.php will be placed in your /usr/local/k3s directory on the IFS.

Once setup and called the deployment will download the latest version available on the K3S FTP server and install it on your setup.

To install / update the interface you will call:

CALL PGM(EXT_5DEV/DEPLOYMENT) PARM(EXT)

(E) Miscellaneous System changes

1) Subsystem and Job queue

Create a new subsystem and associated job queue called WEB_BATCH which will be used for R6 reports and K3S scheduled jobs.

CRTSBSD SBSD(QGPL/WEB_BATCH) POOLS((1 *BASE)) MAXJOBS(1) TEXT('K3S API batch Jobs')                                                                  
CRTJOBQ JOBQ(QGPL/web_BATCH)    
ADDJOBQE SBSD(QGPL/web_BATCH) JOBQ(QGPL/web_BATCH) MAXACT(1)  
CRTCLS CLS(QGPL/web_BATCH) RUNPTY(40)     
ADDRTGE SBSD(QGPL/web_BATCH) SEQNBR(9999) CMPVAL(*ANY) PGM(QSYS/QCMD) CLS(QGPL/web_BATCH)
STRSBS SBSD(web_BATCH)

2) Libraries

Three new permanent libraries will be created on your machine*.

  1. K3S_5WEB - new standard K3S library that must be backed up. This is noted in section F of this document

  2. K3S_5API - used for the API refresh process. This does NOT need to be backed up, but must exist on your machine.

  3. K3S_5OBJBK - used for the API refresh process. This does NOT need to be backed up, but must exist on your machine.

  • A few temporary libraries will also be installed on your machine, but these are for the setup phase. Once installation is complete they will be removed.

3) Save files

Several temporary save files will be downloaded to your machine. These will be noted with the text of ‘temp save file.’ These can be deleted after the install is complete.

(F) Adjustments needed for Night job

1) These night job programs will need adjustments to end R6 data file locks and to write data to new R6 files. Contact K3S if you will be making the adjustments to these programs:

K3S_NIGHT
K3S_X055CL
K3S_X310CL

(G) Scheduled Jobs

1) Two new scheduled jobs will be created that should remain on hold. The jobs are called K3S_5RFRSH (this job refreshes the PHP) and K3S_5DPLOY (this job refreshes the K3S API’s). These jobs should be run by K3S personnel only unless otherwise directed by K3S.

2) Adjust the exit point programs for the weekly and monthly K3S jobs to call a program which will end K3S R6 file locks.

Job K3S_5LEADT; exit point K3S_3065X1
Job K3S_5SERVE; exit point K3S_4040X1 or K3S_4041X1
Job K3S_5RGZPF; exit point K3S_9500X1
Job K3S_5DELET; exit point K3S_9505X1

To end these locks, perform this command, passing it the name of the K3S data library as the one parameter:

CALL       PGM(K3S_5OBJ/AC_UNLKFCL) PARM(&K3S_DTA)

3) Optional: create a new scheduled job called K3S_5START which will restart zend server and start the WEB_BATCH subsystem. This job is not needed if the customer adjusts their QSTRUP program to contain the following:

 STRTCPSVR  SERVER(*HTTP) RESTART(*HTTP) HTTPSVR(ZENDPHP7) 
 MONMSG     MSGID(CPF0000)                                                                                         
 STRSBS     SBSD(WEB_BATCH)                                
 MONMSG     MSGID(CPF0000)

(H) Backup

  • Ensure library K3S_5WEB is added to the backup process.

  • Library K3S_5API and K3S_5OBJBK will NOT need to be added to the backup process, but they must exist on your server.

(I) New version of MMAIL

  • If your company uses MMAIL to email K3S reports, the latest version must be installed.

(J) Adjustments needed for PO Approval

1) RPGLE K3S_1050

Adjust the parameters passed when calling K3S_1100.

(This program is used in production; plan ahead before compiling as users will be actively using this program)

The parameters passed to K3S_1100 should be:

COMP                 1A   
BUYR                 5A   
LOCN                 5A
SUPL                10A
SUPLSUB             10A
SOQSEQN              5,0
POMSG1              25A
POMSG2              25A
POMSG3              25A
POMSG4              25A
POMSG5              25A
POMSG6              25A
POMSG7              25A
PRTHERE              1A
PODATE               d datfmt(*ISO)
ARVDATE              d datfmt(*ISO)
POBLANK             10A
POTYPE               1A
LOCNFRM              5A
LOCNTO               5A
WORKSTN             10A
HOLDBEG              d datfmt(*ISO)
HOLDEND              d datfmt(*ISO)
HLDREAS             40A
SKIPLT               1A
USER                10A 
USERA01              1A
USERA02              1A
USERA03              1A
USERA04              1A
USERA05              5A
USERA06              5A
USERA07             10A
USERA08             10A
USERA09            100A
USERA10            100A

2) RPGLE K3S_1100

Adjust the incoming parameters and adjust the parameters passed to K3S_1101CL.

(This program is used in production; plan ahead before compiling as users will be actively using this program)

The parameters passed to K3S_1100 should be:

COMP                 1A   
BUYR                 5A   
LOCN                 5A
SUPL                10A
SUPLSUB             10A
SOQSEQN              5,0
POMSG1              25A
POMSG2              25A
POMSG3              25A
POMSG4              25A
POMSG5              25A
POMSG6              25A
POMSG7              25A
PRTHERE              1A
PODATE               d datfmt(*ISO)
ARVDATE              d datfmt(*ISO)
POBLANK            10A
POTYPE              1A
LOCNFRM             5A
LOCNTO              5A
WORKSTN            10A
HOLDBEG             d datfmt(*ISO)
HOLDEND             d datfmt(*ISO)
HLDREAS            40A
SKIPLT              1A
USER               10A 
USERA01             1A
USERA02             1A
USERA03             1A
USERA04             1A
USERA05             5A
USERA06             5A
USERA07            10A
USERA08            10A
USERA09           100A
USERA10           100A

When calling K3S_1101CL, add 10 parms to the end of the list to account for USERA01 - USERA10.

3) CLLE K3S_1101CL

Adjust the incoming parameters, and (optional) adjust the parameters passed to the custom program that writes the PO to the customer’s interface files.

(This program is used in production; plan ahead before compiling as users will be actively using this program)

Add 10 parms to the end of the list to account for USERA01 - USERA10:

USERA01            1A
USERA02            1A
USERA03            1A
USERA04            1A
USERA05            5A
USERA06            5A
USERA07           10A
USERA08           10A
USERA09          100A
USERA10          100A

Additionally, pass the additional 10 parms for USERA01 - USERA10 to the RPGLE program that writes the PO information to the customer’s system. This change is only necessary if the customer is passing valid information in the USERA01 - USERA10 fields.

4) Custom RPGLE program

This change is only necessary if the customer is passing valid information in the USERA01 - USERA10 fields. Adjust the RPGLE program that writes the PO to the customer’s ERP system to accept 10 additional incoming parms for USERA01 - USERA10. This program is typically called something like: K3S_PUT_PO, K3S_CRTPO, etc.

5) CLLE K3S_7020CL

This is a NEW program that will call RPGLE program K3S_POPARM. API AR_PODORDR calls K3S_7020CL to receive the next PO#, PO type, arrival date, as well as any default values for customized fields on the PO header screen. Ensure the object exists in the 5MOD library, but likely no adjustments are needed for this program.

6) RPGLE K3S_POPARM

This is a NEW program that will return the necessary values to populate the PO header screen, such as next PO#, PO type, arrival date, as well as any default values for customized fields on the PO header screen. This program mimics the function of K3S_5MOD/K3S_1050, i.e. any modifications made to K3S_1050 should be made to this program.

7) RPGLE K3S_POCHCK

This is a NEW program that will validate the custom parameters on the PO approval screen, should the customer have any modifications to their PO approval screen. An error code will be returned if the user enters an invalid choice in a custom field.

This program will be called by AR_APRORDR. The parameters passed should be:

COMP            1A
COMPCOD         3A
USER           10A
ERRORS          1A
ERRMSG        100A
ERRFLD         20A   
BUYR            5A   
LOCN            5A
SUPL           10A
SUPLSUB        10A
SOQSEQN         5,0
PONUMBER       10A
USERA01         1A
USERA02         1A
USERA03         1A
USERA04         1A
USERA05         5A
USERA06         5A
USERA07        10A
USERA08        10A
USERA09       100A
USERA10       100A

8) CUSTOM FIELDS FOR PO APPROVAL

If the customer has custom fields on the PO approval screen, adjust table code type APR. For each value listed, Flag1 = 1 to enable the field for use on the screen. Set Flag2 = 1 to require the fields for PO approval. If FLAG2 = 0, then the user does not have to specify a value for this field in order to allow PO approval.