MCP PWB/Copy Utility


by Paradigm Corporation
Contents:

PWB/COPY is a utility for Unisys MCP systems that recursively copies whole directories of source files from MCP file systems to SMB/CIFS shared directories. It converts MCP source to standard text files in PWB (Programmers Workbench) format.

This project is part of the UNITE Source Code Repository hosted on SourceForge.

Description

PWB/Copy converts directories of source files residing in Unisys MCP file systems to PWB format and transfers the converted files to SMB/CIFS shared directories on other networked systems.

PWB format is an ordinary Microsoft Windows text file (i.e., with carriage-return/line-feed delimiters), but with the text lines formatted in the specific way required by the Windows-based Programmers Workbench editor (formerly known as NX/EDIT). Essentially, text lines in these files are formatted identically to source records in the MCP environment, including trailing spaces and the positioning of any sequence number or patchmark fields. The PWB editor is very fussy about this format, and will refuse to edit a file that does not meet its requirements. It does have an import tool, however, that will convert most text file formats into the form it requires.

SMB/CIFS is commonly known as "Windows networking," and is the protocol used by Windows to support shared directories and mapped drives. It is also the protocol used by Samba on Linux/Unix (*NIX) systems.

PWB/Copy provides much the same capability as the Unisys MCP File Copier utility that is part of the standard software release. One big difference is that PWB/Copy runs from within the MCP environment, while the File Copier utility, and its command line cousin, MCPCopy.exe, are Windows programs. Another big difference (which is what led to PWB/Copy's development) is the way in which file names that refer to both a file and a directory are handled:

See the PWB editor on-line help file for the correspondence between its file name extensions and MCP FILEKIND values, and the discussion of the FILEKIND attribute in the File Attributes Programming Reference Manual for the columnar layout of various types of source files.

PWB/Copy is written in DCAlgol, a variant of Unisys MCP Extended Algol. It uses the GETSTATUS API to search MCP directories and the Redirector virtual I/O handler to implement SMB/CIFS file access across a network.

Installation and Configuration

Download the ZIP file, which contains the source for PWB/Copy and a couple of example WFL jobs showing its use. These files are in MCP PWB (Programmers Workbench) format. The decompressed source can be uploaded to an MCP environment using the PWB editor, the MCP File Copier utility, the Windows Explorer extension for MCP Client Access Services, the MCP's SYSTEM/NXSERVICES/PCDRIVER utility program, or FTP.

Compile PWB/Copy program with DCAlgol. If your site has not licensed Algol (which includes DCAlgol), you can compile PWB/Copy with DMAlgol instead. No special compiler options or run-time task attribute settings need be compiled into the codefile.

Running PWB/Copy

PWB/Copy has no parameters or command syntax. It is configured entirely through the use of file attributes. The following example shows the basic idea:

    RUN OBJECT/UTIL/PWB/COPY;
        FILE DISK=SRCE/UTIL ON LIBPACK;
        FILE SHARE (FILENAME=TEST/UTIL,
            IOHSTRING="SERVER=WINSRV SHARENAME=TESTSHARE TIMEOUT=5");

The file DISK specifies an MCP file or directory of files that is to be copied to the SMB/CIFS share. This logical file is also used to read the physical MCP files as they are being transferred. The user should not assign any attributes of this file, other than FILENAME, LFILENAME, TITLE, LTITLE, or FAMILYNAME. If no FILENAME is specified, all files under the user's directory will be examined for transfer (based on the special standardform name 48"030100"). To specify all files under a given usercode (e.g., USAH), use the alternate form for indicating a usercode in a file name, thus:

    FILE DISK=*USERCODE/USAH ON PROGPK;

Only one MCP directory of files can be converted and transferred in one execution of PWB/Copy. All subdirectories of the specified MCP directory will be included in the transfer, however.

The file SHARE specifies the SMB/CIFS destination. It is internally declared by default with the attribute REDIRECTION=TRUE, which implies KIND=VIRTUAL, IOHLIBACCESS=BYFUNCTION, and IOHFUNCTIONNAME="REDIRSUPPORT". It is also declared to translate the MCP source text to ASCII in the converted files.

Normally, the IOHSTRING attribute for this file should specify the server and SMB/CIFS share name, with the FILENAME or LFILENAME attribute specifying the directory under the share where the files will be transferred. Alternatively, a pseudo-UNC form of FILENAME attribute can be used to specify the server and share, e.g.,

    FILE SHARE (FILENAME=*UNC/SERVERNAME/SHARENAME/DIR1/DIR2,
        IOHSTRING=" ... ");

Other options exist for specifying the share name and other IOHSTRING parameters. See the Redirector documentation in the I/O Subsystem Reference Manual for details on the IOHSTRING attribute, file titles, user credentials, and connecting to remote SMB/CIFS shares.

If no FILENAME attribute is defined for the SHARE file, converted files will be stored starting at the root folder of the share. No attributes other than IOHSTRING and one of the FILENAME variants should be equated for this file.

The nodes of the MCP source file names below those specified for the title of the DISK file will be preserved when transferring files to the SMB/CIFS share, except that the final node will have a PWB extension appended to it based on the value of the MCP file's FILEKIND attribute.

Only FILEKINDs that have a corresponding PWB extension defined, plus MCP printer-backup (spool) files and a few others, will be converted and transferred. All other files in the source directory will be ignored. Record-oriented files will be formatted according to PWB conventions concerning record size and trailing spaces. Printer-backup files will be formatted as line-delimited files with CR/LF/FF carriage control. Byte-stream files will be transferred as is. All text is written to the remote file in ASCII; as such this program is not recommended for use with EBCDIC data files containing packed-decimal or binary data.

In addition to DISK and SHARE, PWB/Copy has a file LINE, of KIND=PRINTER. This file records a trace of the MCP directories traversed and the results of files transferred. In most cases, this output is not very useful, so you may wish to suppress it using the following file equation:

    FILE LINE (DUMMYFILE);

The Redirector is a very chatty interface, and may display numerous messages as it opens and closes connections with the remote system. PWB/Copy must probe for the existence of directories and create them on the remote share if they do not already exist. These activities typically generate messages that may appear to be errors, but merely represent unsuccessful probes of the remote file system. A very common (and almost always benign) message from the Redirector while running PWB/Copy is:

REDIRECTOR:SMB make new directory (SMBmkdir) failure. SMB Error: ERRdos, Directory invalid

If you see the following, though, you have a credentials problem:

REDIRECTOR:SMB session log on (SMBsesssetupX) failure. SMB Error: ERRdos, Access denied

If you see the following, especially if preceded by a delay at least as long as the IOHSTRING timeout you have specified, the MCP Redirector cannot locate the remote host—check that you have the correct SHARENAME parameter, then try using a fully-qualified DOMAINNAME or IPADDRESS parameter in IOHSTRING:

REDIRECTOR:Device/File open failed. Timeout Opening NetBIOS Session.
REDIRECTOR:Result Descriptor=000000 000000

So, What Good Is It?

PWB/Copy is useful when you want to move large numbers to MCP source code files to a Windows or *NIX environment.

Since it runs in the MCP environment, PWB/Copy can access files in subdirectories that would otherwise be hidden to SMB/CIFS clients because there happens to be a file with the same name as the directory. It is not uncommon in MCP shops to have source file names of the following form:

    (LIB)SOURCE/APP/SOME/REPORT
    (LIB)SOURCE/APP/SOME/REPORT/SPECIALCASE
    (LIB)SOURCE/APP/SOME/REPORT/OLDVERSION

SMB-based source copy tools running from outside the MCP (such as MCP File Copier) will only see and transfer the first of these three files. PWB/Copy will find and transfer all of them.

PWB/Copy will only convert and transfer files with FILEKINDs that map to a recognized PWB file name extension or MCP printer-backup. It will skip over object codefiles, DMSII and ISAM files, etc.

PWB/Copy will preserve the subdirectory structure that it finds and automatically create subordinate directories on the remote share as necessary. Existing directories on the remote share will be preserved, unless PWB/Copy transfers a file with the same name as the remote directory (but given that the file names will all have PWB extensions, a conflict with a directory name is unlikely). Existing files on the share with the same name as one being transferred by PWB/Copy will be replaced, however (as is normally the case in the MCP).

Once the files are transferred to the remote share, what can you do with them there? The short answer is anything you want, but here are some things we've found useful:

Project Participation

We welcome others to participate in this project and submit contributions to the software and documentation. Please contact the Project Admin for information on joining the project.

If you wish to make changes to PWB/Copy, please try to preserve the existing sequence numbers in the source code lines as much as possible. Sequence numbers are a foreign concept in most development environments, but they are an important part of serious development for MCP software, so try to change them as little as possible.

References

Unisys documentation is available without cost on their support web site, http://support.unisys.com.

__________
1 Actually, the MCP doesn't have directories of files, per se. Instead, it has multi-level file names. What we term a "directory" is simply a non-terminal node in the name. The file system indexes file names by their nodes and the hierarchical relationship of those nodes, but there is only one directory structure per disk family (sometimes called the "FLAT," and stored on the family as *SYSTEMDIRECTORY/nnn). It is a flat, unindexed file containing variable-length file header entries. The index structure (the "FAST") is organized as a tree, and provides the mechanism to efficiently locate all of the file names that have the same set of leading nodes. The FAST can be rebuilt from the FLAT as necessary (which, fortunately, is seldom).

Revised: 2014-04-12 Project Web Hosted by Get MCP PWB/COPY Utility at SourceForge.net. Fast, secure and Free Open Source software downloads