Introducing the WebDocs iSeries Security Guide

When training iSeries or network administrators on the WebDocs iSeries content management system, inevitably the question of security comes up – as well it should. Nevertheless, we have found that when a hapless administrator, new to WebDocs (or even, perhaps, to the iSeries itself) is inundated with information regarding securing their WebDocs environment, the potential for missing something crucial is all too often realized. Having access to a reference document such as the RJS security guide  gives the canny WebDocs administrator an effective way to make sure that no aspect of security is mistakenly omitted. The content of the guide has been grouped by related topics to allow one to find answers to specific questions quickly.

Read the rest of this entry »

Printer Control Language, or PCL, appears to many as a standardized format but in reality it can be quite different when produced by drivers for different printers by different manufacturers.

As a result, we have accommodated several methods for creating PCL output and printing into our iForms product. This flexibility is an asset, but it can be confusing at first. The following document provides an overview of the strengths and weaknesses of each approach, allowing you to make an informed decision on what method or methods to use when printing with iForms.

This guide is divided into the following sections:

1. Printing Methods Available in iForms
2. Additional Considerations for Printing in iForms

View the guide.

WebDocs iSeries uses the IFS directory /RJSTEMP and the library RJSTEMP to store information and files temporarily. In general, it will attempt to clean up after itself, but there are situations which arise that do not perform clean up operations. As a result, files will gradually accumulate, taking up disk that could otherwise be used for other processes.

The RJSTEMP library

The RJSTEMP isn’t only used by WebDocs iSeries, and it’s considered unsafe to simply do a CLRLIB except immediately following an IPL, and before any RJS Software processes have started. Generally the only reason that the library tends to expand is if new user sessions are being created without being cleared. Older versions of WebDocs iSeries were particularly prone to this. Versions of WebDocs above 3.08 should have the command:

DOCRMVSESU USER(*ALL)

which can be scheduled to run on a nightly or weekly basis. At version 3.14 or above, the DOCSESPRG command is available as well to manage session files during operations. (for more information, see last week’s article, item 2: Problems with folder or document access).

A simple query can determine whether RJSTEMP has grown due to sessions that have not been cleared:

SELECT COUNT(*) FROM RJSIMAGE/DOCSES00

The following query can be used to count the actual number of temporary tables in the RJSTEMP library:

SELECT COUNT(*) FROM QSYS2/SYSTABLES
WHERE SYSTEM_TABLE_SCHEMA = 'RJSTEMP' 

Clearing RJSTEMP

Clearing the RJSTEMP library should only be done when the system is in a restricted state, or when no RJS processes are running.

CLRLIB RJSTEMP

The /RJSTEMP IFS folder

The RJSTEMP directory is a directory that is created on the root (‘/’) of the IFS by RJS Software Products and is used as a temporary working folder for many RJS Software Systems solutions.

The RJSTEMP directory can be accessed by running the following command:

 WRKLNK '/RJSTEMP'

When to Purge the RJSTEMP Directory

Care should be taken when purging the RJSTEMP directory. Do not run a purge command if there are any RJS Software Systems processes currently running on the iSeries or on a Server that is connecting to the iSeries as it could cause those applications to error and/or hang.

 It is strongly recommended that you limit the purging process to one of two possible occasions:

1. If your company typically allows most of their jobs to end at night and use a scheduler to start them off again early in the morning, you could schedule the purge command to run before you start up the jobs running RJS Software Systems solutions.

2. When you IPL your iSeries, the purge command can be added to your system start-up before the typical jobs get started.

How to Purge the RJSTEMP Directory

The command below will allow you to purge a single file or an entire directory of files on the IFS. Due to the fact that this command is extremely easy to use and the fact that it permanently removed files from the IFS, please make sure that you have read the security warnings and suggestions above.

1. To Purge a Single File from the IFS

The following example assumes that I want to purge the file TEST.PDF from the ‘/RJSTEMP’ directory on the IFS.

RMVLNK OBJLNK('/RJSTEMP/TEST.PDF')

2. To Purge All Files from Single Directory on the IFS

The following example assumes that I want to purge all the files from the ‘/RJSTEMP’ directory on the IFS.

RMVLNK OBJLNK('/RJSTEMP/*')

3. To Purge Select Files from Single Directory on the IFS

The following example assumes that I want to purge all the files that start with the letters “RJS” from the ‘/RJSTEMP’ directory on the IFS.

RMVLNK OBJLNK('/RJSTEMP/RJS*')

As a WebDocs iSeries administrator, if something goes wrong your users will look to you to find, and fix, the matter. Simply knowing where to look when an initial error message is unclear can resolve a huge percentage of difficulties. I will cover the most common situations in this article. These instructions are designed to help an administrator clarify the issues at hand, but they may not always be sufficient to correct the issue. In the event of escalating an issue to RJS Software Support, simply having the details from the logs listed below will help speed the resolution of any support tickets immensely.

1. Problems with the default web interface.

WebDocs iSeries ships with a web interface, and in most situations, meaningful errors will display within the interface. In the cases where the message is a generic “Error occurred”, you can look at the Apache instance job logs for more information. On the iSeries, at a command line, run:

WRKSBSJOB QHTTPSVR

Your results should look something like this:

Opt  Job         User        Type     Status  Function
_    ADMIN       QTMHHTTP    BATCH    ACTIVE  PGM-QZHBMAIN
_    ADMIN       QTMHHTTP    BATCHI   ACTIVE  PGM-QZSRLOG
_    ADMIN       QTMHHTTP    BATCH    ACTIVE  PGM-QLWISVR
_    ADMIN       QTMHHTTP    BATCHI   ACTIVE  PGM-QZSRHTTP
_    ADMIN       QTMHHTTP    BATCHI   ACTIVE  PGM-QYUNLANG
_    WEBDOCS     QTMHHTTP    BATCH    ACTIVE  PGM-QZHBMAIN
_    WEBDOCS     QTMHHTTP    BATCHI   ACTIVE  PGM-QZSRLOG
_    WEBDOCS     QTMHHTTP    BATCHI   ACTIVE  PGM-QZSRHTTP
5    WEBDOCS     QTMHHTTP    BATCHI   ACTIVE  PGM-QZSRCGI
_    WEBDOCS     QTMHHTTP    BATCHI   ACTIVE  PGM-QZSRHTTP
5    WEBDOCS     QTMHHTTP    BATCHI   ACTIVE  PGM-QZSRCGI
5    WEBDOCS     QTMHHTTP    BATCHI   ACTIVE  PGM-QZSRCGI

Please note that your job names may vary. The jobs whose Function ends in CGI are the jobs you want to look at. Put a 5 in front of the job (or jobs) to work with it, and choose option 10 to look at it’s job log. Press F10 to get more details, and F18 (Shift+F6) to go to the bottom of the job log, which should show you the error message in full detail. If you place your cursor on the error message, you can press F1 for additional details, and then F9 to see which program the message came from. If you need to send the job log to RJS Software Support, note the job name, user and number across the top of any of these three screens.

Job:   RJSIMAGE      User:   QTMHHTTP       Number:   131940

Enter them into a DSPJOBLOG command, with the output set to *PRINT. A WRKSPLF command will find the newly created spool file for you, which can then be emailed to our support team.

DSPJOBLOG JOB(131940/QTMHHTTP/WEBDOCS) OUTPUT(*PRINT)             

If it appears to be an Apache error, rather than an application error, you can look at Apache’s logs on the IFS using the command:

WRKLNK OBJ('/www/<your server name>/logs')

For debugging or to better understand what database queries are being made, you can set the DEBUGSQL data area in RJSIMAGE to *YES.

CHGDTAARA DTAARA(RJSIMAGE/DEBUGSQL) VALUE(*YES)

This will display the SELECT statement on the top of the page in the WebDocs browser session. On recent versions of WebDocs iSeries, this view is restricted to WebDocs iSeries users that have the Administrator flag set to ‘Y’ in their user profile. On older versions the SQL statements appeared for all users.

2. Problems with folder or document access

WebDocs iSeries uses sessions to manage user security. A session is a static snapshot of a given user’s rights at the time of the session’s creation. As an administrator, changes you make to user or group securities (revocation of rights to a document type, adding a folder, etc.) will not appear to users who are active with sessions that were created prior to the change. An option 6 on the user or group account from the Work with Users and Groups screen will purge any active sessions, forcing users to log in again in order to see current security (for things that need to take effect immediately). As an administrator, it is recommended that you run DOCRMVSESU to clear out all sessions on a nightly or weekly basis.

DOCRMVSESU USER(*ALL)

Alternately, you can submit DOCSESPRG as a job.

                    Purge sessions periodically (DOCSESPRG)                

Minutes between purges . . . . . DELAY          60               

Minutes not used . . . . . . . . INACTVTIME     120              

Time to end job  . . . . . . . . ENDTIME        ___

Every 60 minutes, the job will ‘wake up,’ and purge all sessions that have been inactive for more than two hours. These are configurable, according to your needs.

3. Troubleshooting the .NET API

Many of the ancillary products connect and check-in to WebDocs iSeries using our .NET API. If a problem occurs, with an unclear message from the PC application, you can run the following command to view a list of active jobs – remember to leave the error message up on the PC application, or there is a chance that the job will end.

WRKACTJOB JOB(QZRCSRVS)

There may be a number of jobs that appear – put a 5 on all that appear and peruse each to determine which is the job associated with the troubled application. Alternately, you can look up the job by the current user (the original job user will always be QUSER).

WRKOBJLCK <USERNAME> *USRPRF

This can restrict the number of jobs you have to dig through to find the problem job.

4. Debugging Exit Programs

If you have developed WebDocs iSeries exit programs in-house, an elegant way of troubleshooting or debugging the programs is using Service Entry Points. This allows a breakpoint to be triggered, without knowing in advance what job it will come from. This is ideal when testing check-ins from applications that connect via the .NET API, although there are a number of other equally valuable use cases. A full discussion on the topic, with links to IBM’s documentation is available on our support wiki.

5. After IPL

Finally, please ensure that all WebDocs iSeries related jobs are being started after an IPL. These include, but are not limited to:

- The Apache web server itself
- DOCMOUNT (if you are using NFS shares)
- DOCSESPRG (if applicable)

NFS has long had a tentative relationship to security. As with its cousin, CIFS/SMB (more commonly know as Windows File Sharing), security was not an area of primary focus. The elements of security that exist are significant, but they are nontrivial to implement, particularly across operating systems and with third-party applications.

In the past, customers who implemented NFS shares with WebDocs iSeries have lived with a single layer of security: IP address restriction. When a share is defined, rights are also defined for incoming requests. By default on most systems, the ALL_MACHINES class had Read authority to the share. This means that any machine on the network may mount the share and read its contents. Setting ALL_MACHINES to none and then giving read & write authority to a specific IP address (in this case, it would be the IP address of the LPAR that WebDocs iSeries is installed on) prevents machines at all other IP addresses (barring advanced spoofing attacks and the like) from mounting the share at all.

Likewise, on the IFS it had been routine to simply give *PUBLIC read, write and execute authority to the IFS folder that the share is mounted to. This folder was typically directly under the root folder, and would be called /RJSIMAGEDOCNFS or /WEBDOCSSHARE or similar. This practice is without consequence if IFS access is restricted to security officers, but in contexts where all general users have IFS access from the 5250 emulator or via a mapped drive on Windows, this became unacceptable. The practice we have been advocating recently has been to create a folder hierarchy. A parent folder is secured to only the required parties: typically the user created for RJS-related jobs and security officers. It’s child folder is then configured with *PUBLIC *RWX to allow for successful mounts. Users who do not have access to the parent cannot navigate, then, to the child.

There have been some instances, however, for which even these measures are not adequate. Whether it is the issue of IP address spoofing, or that of users with *IOSYSCFG mounting the share to folders they do have access to, there can be a need to tighten things further. This may be done with mapping User IDs. On Windows and UNIX-based operating systems, each user name has an associated number, known as the user ID or UID. The number schemes differ somewhat between Windows-based and UNIX-based operating systems, but if you are an administrator on the server and client machines, you can create a new user (or users) with the same UID, and then restrict access to a share to that user (or users). How this is done differs across operating systems.

Instructions for configuring Windows 2008 Server to work with WebDocs iSeries using UID mapping are available here. Instructions for Windows 2003 Server, Fedora, openSuSE and Ubuntu Server are forthcoming.

As always, please feel free to call our Technical Support at 1-800-RJS-SOFT or email in to support@rjssoftware.com with questions and comments.

In the beginning there was ODBC, and it was good enough. Microsoft’s Excel format was a compelling tool, and anyone with an eye for databases saw it’s utility, both as an input into existing database systems but more particularly, as a way to generate and distribute reports from these same database systems.

RPG on the iSeries makes it trivial to work with DB2, the native database on OS/400, but other systems can be more difficult, and as you get to the more esoteric databases, there may be no support at all. However, nearly every database in existence has an ODBC driver or an OLE DB provider (courtesy of the MDAC framework). Our RPG2SQL product was designed around the flexibility of ODBC. It consists of two pieces; a library on the iSeries which contains the function calls available to intrepid RPG programmers, and a PC component which parlays between our library and various ODBC drivers, installed in Windows’ Data Sources control panel.

This two-(or more)-way communication stream looks roughly like this:

This comes back to Excel in important ways. Microsoft has an ODBC driver for Excel, and our original example of reading from an Excel spreadsheet showcases this method (it’s still available, in the SOURCE file in the RJSRPGSQL library; you can use WRKMBRPDM or Option 10 from the RJSRPGSQL menu to find it. The program is called SQTEST04R).

An example from SQTEST04R shows RPG2SQL opening a connection to an existing Excel spreadsheet using the Microsoft Excel ODBC driver:

SQL_DBOpenConn(SQL_Socket:'Driver={Microsoft Excel Driver (*.xls)}; DriverID=790; DBQ=c:\program files\rpgsqlsv\; nameaddr.xls; DefaultDir=c:\program files\; Pwd=;)

However, ODBC/OLE DB has its limitations (for example, this, this and this). Development on the Excel ODBC driver appears to have ended around 1998. In its stead, Microsoft added OLE automation that granted access to the data-management aspects of the application, permitting changes to be made with the full flexibility of Excel, modifying, for example, cell formatting or coloration. In late 2003, support for this method of communication with Excel was added to RPG2SQL. To differentiate these function calls from those of the ODBC method, XLS_ is prepended to each function name, instead of the SQL_ of the ODBC functions.

The communication method is similar to, but distinct from, the ODBC method of communication:

The SQTEST29R source sample shows RPG2SQL opening a spreadsheet as in SQTEST04R, but this time using the OLE automation calls:


*-------------------------------------------------------------------------
* ** Launch MS Excel and make it visible
*-------------------------------------------------------------------------
C Eval Rtn = XLS_Launch(SQL_Socket)
C Eval Rtn = XLS_Visible(SQL_Socket:1)

*————————————————————————-
* ** Open spreadsheet file
*————————————————————————-
C Eval Rtn = XLS_Command(SQL_Socket:
C ‘FILEOPEN’:
C ‘C:\Program Files\RPGSQLSV\nameaddr.xls’)

*————————————————————————-
* ** Set the initial spreadsheet positions
*————————————————————————-
C Z-ADD 0 EOF1
* ** Set to spreadsheet row 2 (Column headings are in row 1)
C Eval CurRow = 2
* ** Our record in the spreadsheet is comprised of columns 1 – 13)
C Eval StartCol = 1
C Eval EndCol = 13

*————————————————————————-
* ** Read all records from our sample spreadsheet
*————————————————————————-
C DOW EOF1 = 0

*————————————————————————-
* ** Read second delimited record from spreadsheet.
* ** The first row is the header row in our sample Excel file.
* ** so we will not read it in.
*————————————————————————-
C Eval RtnRecord = XLS_GetDelimRec(SQL_Socket:
C CurRow:StartCol:EndCol:”:”:’;')

The full code sample may be downloaded here.

Best practices: When referencing Excel files on remote systems, use the UNC path rather than mapped drives. Mapped drives will not work by default if the RPG2SQL PC component is running as a Windows service.

The flexibility of directly interacting with Excel extends far beyond mere data entry, with functions such as FILESAVEAS, FILEPRINT, SETACTIVECELLFORMULA, SETACTIVECELLFONTNAME and SETACTIVECELLNUMBERFORMAT as but a few examples. Additionally, you can convert Excel macros to scripts and call them via RPG as well, expanding one’s range of possibilities immensely.

If you’re using the old, ODBC method, that’s not ideal but if it’s not broke, the fix isn’t strictly required, and the functionality isn’t going away. But if you’re coming to RPG2SQL for the first time, do yourself a favor and explore the XLS functions. The RPG2SQL manual has detailed information on each function, and RPG prototypes for the functions, and the RJSRPGSQL library on the iSeries has source samples (SQTEST29R, and SQTEST26R) which you can modify and compile at your leisure.

As always, if you have specific questions you may contact RJS Software Systems at 1-800-RJS-SOFT during business hours, and we’d be happy to talk.

This week I had an interesting discussion with a customer, which dovetailed nicely with the two topics we’ve addressed thus far at RJS Hacks: changing file paths in WebDocs iSeries and mounting remote filesystems into the IFS.

The situation is as follows:

Company X stores all their documents locally on the IFS. Eventually, this is deemed to take up too much space, and a fileserver was built to hold all but the most recent documents. A directory was created for each year/month on the fileserver, and each directory had its own NFS share, and was mounted separately into its own, corresponding, IFS directory.

This was ungainly, and unpleasant to manage, so we were asked to help clean things up. They created a new folder structure on the fileserver, but they were hesistant about resetting the database to re-run the DOCMOVLOC command, and rightly so. Because the file origin and destination were both on the fileserver, it would be faster to simply move the files to the new folder structure manually and then manually update WebDocs to point to the new location.

We will be directly editing two of the most important physical files in WebDocs: DOCS00 and DOCVER00. Make a backup of the RJSIMAGE library, and make sure that no one is using the system, and that there are no processes checking in documents while following the steps below.

For this example, the IFS path /RJS/NFS/Bad/Folder/Structure represents the old mount location on the IFS, and /RJS/NFS/Improved/Folder/Structure/ represents the new. Replace these paths with whatever is relevant on your system.

Once all the documents had been manually moved to their new locations, we ran the following two queries:

Query 1: Unsets the fields that flag a document as ‘Archived’, modifier the fields to point to the new location (DOCVER00)
update rjsimage/docver00 set vdocpath = replace(vftppath, '/RJS/NFS/Bad/Folder/Structure/', '/RJS/NFS/Improved/Folder/Structure/'), vdocfile = replace(vftpfile, '/RJS/NFS/Bad/Folder/Structure/', '/RJS/NFS/Improved/Folder/Structure/'), varchsel = '', vftpfile = '', vftppath = '', vdiskstat = '' where vftppath like '/RJS/NFS/Bad/Folder/Structure/%'

Query 2: Unsets the fields that flag a document as ‘Archived’, modifier the fields to point to the new location (DOCS00)
update rjsimage/docs00 set diskstatus = '', darchsel = '', docpath = (select VDOCPATH from rjsimage/docver00 join rjsimage/docs00 on vdocid = docid where vdocpath LIKE '/RJS/NFS/Improved/Folder/Structure/%'), docfile = (select VDOCFILE from rjsimage/docver00 join rjsimage/docs00 on vdocid = docid where vdocpath LIKE '/RJS/NFS/Improved/Folder/Structure/%') where docid = (select VDOCID from rjsimage/docver00 join rjsimage/docs00 on vdocid = docid where vdocpath LIKE '/RJS/NFS/Improved/Folder/Structure/%')

What is NFS?

Network File System (NFS) is a network file system protocol originally developed by Sun Microsystems in 1984,[1] allowing a user on a client computer to access files over a network in a manner similar to how local storage is accessed. NFS, like many other protocols, builds on the Open Network Computing Remote Procedure Call (ONC RPC) system. The Network File System is an open standard defined in RFCs, allowing anyone to implement the protocol. (NFS on Wikipedia)

Integrated File System – on IBM midrange & mainframe systems (e.g. OS/400, MVS, VM/CMS), the POSIX compatible filesystem provided by the operating system, as opposed to the traditional non-POSIX filesystem it also supplies

Sources: IFS on Wikipedia, IBM i on Wikipedia

DOCMOUNT calls the MOUNT command on your system with the following parameter values:

MOUNT TYPE(*NFS) MFS(&FILESYSTEM) MNTOVRDIR(&IFSDIR)
OPTIONS('rw,nosuid,retry=5,rsize=8096,wsize=8096,timeo=20,retrans=2,
acregmin=30,acregmax=60,acdirmin=30,acdirmax=60,soft')
CODEPAGE(*BINARY *ASCII)

These are the default options suggested by IBM when running the mount command interactively, except we soft mount.

NFS v1 was never formally released (per IBM’s documentation). NFS v2 and v3 will work on OS/400 V5R1 and above. NFS v4 was added to V6R1 via PTFs, and should be in the base release for V7R1. It is not available for versions of OS/400 below V6R1.

More precisely;
"To use NFS, the OS/400 must be at R370 or higher and TCP/IP already configured and working. It replaces FSS/400 which was available on previous releases. NFS and FSS/400 are not compatible with each other. The OS/400 version of NFS is a ported version of Sun Microsystems Version. 2 product."
Source: IBM internal KB

• IBM Systems Magazine: A Look at File Systems
• Mount (General Computing)
• Mounting (UNIX)

Installation & configuration instructions per operating system will be added to this article at a later date.

RJS Hacks is a weekly column presenting detailed tutorials for novice and seasoned administrators alike. Questions and comments are encouraged, and if you have a topic you would like to see discussed please let us know.

In Part I of this series (Reorganizing documents and folders in WebDocs iSeries), you learned how to reorganize the WebDocs iSeries folder structure to better suit your needs. However, you did not change the location of where the documents were actually stored on the IFS. Because WebDocs maintains a separation between its internal file structure and the operating system’s, you can organize documents for your users in one manner, while organizing them on the IFS in an entirely different manner. This article takes you through the steps of reorganizing the folder structure on the IFS.

This article assumes all of your documents are saving to a single IFS location: /RJSIMAGEDOC. Saving documents to a single IFS location has not been a problem for you until recently, but now that the system has been live for a little while the folder is beginning to become a bit ungainly, and takes several minutes for iSeries Navigator to load the several hundred thousand documents it contains. In addition, your nightly backups are taking longer now, and if things continue the backup jobs will take longer than their allotted time. To better handle the present, and in preparation for the future, you’d like to reorganize the documents on the IFS into a folder structure broken down by year, like so:

/RJSIMAGEDOC/2007
/RJSIMAGEDOC/2008
/RJSIMAGEDOC/2009
/RJSIMAGEDOC/2010


This can be done with relative ease, and in a manner that is completely invisible to your users. This article assumes that you have access to an iSeries user profile with *ALLOBJ special authority, that the system was initially installed in 2007, and that you have not reorganized documents on the IFS before. But first, enter the following commands on a command line:

RJSIMAGE/DOCSQL SQLSTM('select count(*) from rjsimage/docver00 where vftpfile ''''')
RJSIMAGE/DOCSQL SQLSTM('select count(*) from rjsimage/docs00 where darchsel ''Y''')

Both counts should return with zero results; if either command returns anything other than zero, please contact Technical Support before going further.

Creating the new folders

Before you attempt to move anything, you will need to create the new folder locations first.

For those who are using a mounted file system, the subfolders will need to be created on the mounted device. For example, if you are mounting an NFS share from a Linux fileserver into the IFS, you will need to create the new folders on the Linux fileserver, not from the iSeries.

To create the new folder locations, enter the following commands on a command line:

CRTDIR DIR('/RJSIMAGEDOC/2007')
CRTDIR DIR('/RJSIMAGEDOC/2008')
CRTDIR DIR('/RJSIMAGEDOC/2009')
CRTDIR DIR('/RJSIMAGEDOC/2010')


Update IFS Paths for Folders in WebDocs

Now you need to ensure that documents entering the system are going to the correct location. Update the existing WebDocs folders to point to this year’s folder (/RJSIMAGEDOC/2010) from the Work with Document Folders menu option:

ADDLIBLE RJSIMAGE
GO RJSIMAGE
Option 11: Work with Document Folders


Replace ‘/RJSIMAGEDOC’ with ‘/RJSIMAGEDOC/2010′ for each folder.

Select documents to be moved

Changing the IFS Path in a WebDocs folder entry specifies where to save new documents that are entering the system, but it does not move any documents already in the system. So the next step is to split the documents that are already in the system into the four subfolders you created by specifying what documents will be moved to each subfolder. To select a range of documents to be moved, set the DARCHSEL field in the DOCS00 physical file to ‘Y’ using the query below:

RJSIMAGE/DOCSQL SQLSTM(‘update rjsimage/docs00 set darchsel = ”Y” where year(chkdate) = ”2007”’)

In your environment, the criteria could be anything that you can query – index values, user IDs, document types, folders, or any combination you can envision.

Moving the documents

All documents checked in to WebDocs in 2007 are now selected to be moved, so your next step is to run the DOCMOVLOC command to begin the move process. The move process will take some time, depending on how many documents you are moving, but the documents will still be available to your users. The command first moves each document to the new location, and checks the document to ensure that it copied correctly. Only then does DOCMOVLOC update the database to point to the new location, and delete the file from the old location. As far as your users are concerned, no change will have occurred. To run the DOCMOVLOC command, enter the following on a command line:

RJSIMAGE/DOCMOVLOC IFSDIR('/RJSIMAGEDOC/2007') CONFIRM1(*YES) CONFIRM2(*YES)

Once the DOCMOVLOC command completes, run the update statement to select 2008’s documents and follow it up with the DOCMOVLOC command going to /RJSIMAGEDOC/2008. Repeat for 2009 and 2010.

Now your documents are neatly split up into subfolders by the year they entered the system. You’ll want to make an annual reminder to create the next folder in the series (/RJSIMAGEDOC/2011 in this example), and change the IFS Paths in the Work with Document Folders menu (or, if you’re a programmer, write a short program to do so automatically).

RJS Hacks is a weekly column presenting detailed tutorials for novice and seasoned administrators alike. Questions and comments are encouraged, and if you have a topic you would like to see discussed please let us know.

Do you find that the folder structure that seemed so simple and concise when you initially set up WebDocs iSeries has become a source of pain and confusion? Documents may be moved en masse, and folder hierarchies may be restructured after the fact, and using the example below we will walk through a sample restructuring. Let’s assume that your current folder structure is as poorly thought through as the example on the screen below.

With some input from the departments affected, you’ve sketched out an alternative. You will do away with the CLERK folder altogether and make ACCOUNTING the parent directory instead, with AP as the child directory inside. Afterwards, you will move all the documents from the old folder structure to the new all at once, instead of working with one at a time.

The instructions in this article assume that you have access to an iSeries user profile with *ALLOBJ special authority, and that your RJSIMAGE library is at version 3.08 or above. If you’re unsure which version you are at, enter the following command on a command line:

DSPDTAARA RJSIMAGE/VERSION

Because we’ll be working directly with the WebDocs database, make sure that no one is using or checking new documents into WebDocs before going any further. If you have additional concerns, please contact Technical Support.

Note: WebDocs’ folder structure is virtual, so this change will not affect where the actual .pdf or .tiff files appear on your filesystem. If you need to move the files on the IFS as well, please see Part II: Moving documents between IFS folders.

How do I discover how the documents are distributed through the current folder structure?

To see what you’re working with, run the following SQL statements to return how many documents exist in each folder:

RJSIMAGE/DOCSQL SQLSTM('select count(*) from rjsimage/docs00 where folder1=''CLERK''')
RJSIMAGE/DOCSQL SQLSTM('select count(*) from rjsimage/docs00 where folder1=''CLERK'' and folder2=''ACCOUNTING''')
RJSIMAGE/DOCSQL SQLSTM('select count(*) from rjsimage/docs00 where folder1=''CLERK'' and folder2=''AP''')


The first query returned for me with 0 results, so there are no documents actually residing in the CLERK folder. The other two have lots of documents, so those are what will need to move.

Creating the new folder structure

On the iSeries, navigate to Work with Document Folders:

ADDLIBLE RJSIMAGE
GO RJSIMAGE
Option 11: Work with Document Folders


You’ll need to create your new directories first. Use F6 to create a new folder.

Set the Folder to ACCOUNTING, the Description to Accounting Reports and keep the IFS Directory the same as the original folder entries. Upon save the Edit Document Folder screen will remain up so that you can create additional directories. Keep the Folder as ACCOUNTING but add AP to the line below. Set the Description to Accounts Payable and the IFS Directory as is. Save this new entry, and then F12 to return to the folder list, with your new folders now present (it may require an F5 to refresh the list).

Setting rights to the new folders

At this stage, it may help to have two 5250 sessions active, so that you can switch back and forth easily. On the one session, put a 9 on the old folders (CLERK/ACCOUNTING and CLERK/AP) to see their securities. On the second session, do the same for ACCOUNTING and ACCOUNTING/AP. Ensure that ACCOUNTING matches with CLERK/ACCOUNTING and ACCOUNTING/AP with CLERK/AP. We don’t want to surprise any users by denying them access to documents they were once able to work with.

Moving documents between WebDocs iSeries folders

You now have a folder to move your documents to. You may now run an SQL update statement to change the WebDocs folder for all documents in CLERK/ACCOUNTING and CLERK/AP to ACCOUNTING and ACCOUNTING/AP, respectively. Because you will be making changes in the WebDocs database, make a backup of the DOCS00 physical file before proceeding.

The first update command moves documents from CLERK/ACCOUNTING to ACCOUNTING:

RJSIMAGE/DOCSQL SQLSTM('update rjsimage/docs00 set FOLDER1 = ''ACCOUNTING'', FOLDER2 = '''' where FOLDER1 = ''CLERK'' and FOLDER2 = ''ACCOUNTING''')

The second moves documents from CLERK/AP to ACCOUNTING/AP:

RJSIMAGE/DOCSQL SQLSTM('update rjsimage/docs00 set FOLDER1 = ''ACCOUNTING'', FOLDER2 = ''AP'' where FOLDER1 = ''CLERK'' and FOLDER2 = ''AP''')

Congratulations, you’ve moved all the documents – in WebDocs at least. In truth, the actual files themselves are in the same IFS directories they always were, but the folders that are presented to your users in the web interface reflect the new structure and naming scheme.

Deleting the old folders

To tidy up, you may clear all securities from CLERK, CLERK/ACCOUNTING and CLERK/AP by returning to the folder menu in RJSIMAGE and using option 9 on each folder in turn. Clear all the Y’s out, and then use option 4 on the folders to delete them.

Displaying the changes to your users

Finally, you will need to purge your users’ old sessions – they will not see the new folders until their existing sessions are cleared. You can force sessions to reload using the DOCRMVSESU command:

DOCRMVSESU USER(*ALL)

When they log into the web interface now, they will now see the new folder structure: