Pull -- A Cross-Platform Tool for File Easy Extracting and Compact Packaging Yao LI Sept. 20, 1997 v. 3.3 Table of Contents 0. What's New in This Release 1. Introduction 1.1 What Is the pull 1.2 What Are the Major Uses of pull 1.3 On Which Platforms pull Works 1.4 In What Ways pull Might Be Used 1.5 How pull Works 2. Obtain and Setup pull 2.1 Which Program Files Are Required and Where They Are Archived 2.2 How to Compile and Link pull 2.2.1 On Unix Platforms 2.2.2 On VMS Platforms 2.2.3 On DOS/MS Windows Platforms 2.2.4 On OS/2 Platforms 2.3 How to Install pull 2.3.1 On Unix Platforms 2.3.2 On MS Windows Platforms 2.3.3 On VMS Platforms 2.3.4 On OS/2 Platform 2.4 How to Customize pull as A Window Application 2.4.1 On Unix Platforms 2.4.2 On MS Windows Platforms 2.4.2.1 Customize pull for Drag and Drop GUI Operation 2.4.2.2 Customize pull for Double-click GUI Operation 2.4.3 On OS/2 Platform 2.4.3.1 Double Click 2.4.3.2 Drag and Drop 3. Usage 3.1 Extracting 3.1.1 Jointly 3.1.2 Separately 3.1.3 Standard I/O (Filter) 3.1.4 Suppress Verbose 3.2 Packaging 3.2.1 One Input File 3.2.2 Two Input Files 3.3 On-line Help Pages 4. Typical Usage Examples 4.1 Extracting 4.1.1 On Unix 4.1.2 On MS Windows and MS-DOS 4.1.3 On VMS 4.1.4 On OS/2 4.2 Packaging 5. Other Related Topics 5.1 Exit Code 5.2 Internally Supported Filename Extensions 5.3 gzip Archive Information 5.4 Viewing and Printing PostScript Files 5.4.1 Viewing A PostScript File 5.4.2 Printing A PostScript File 5.5 uue77 Encoder 6. License, Copyright, and Warranty 7. Troubleshooting 8. Bug Report and Comments 9. History 10. Acknowledgments 11. References ------------------------------------------------------------------------ 0. What's New in This Release * pull ported to OS/2 FAT and OS/2 HPFS; * porting tested onto three more Unix variants: Digital Unix, BSDI BSD/OS, and Linux; * tested on multi-platforms for proper handling of files with no filename extension or without pull internally registered extensions; * converted pull.c from K&R C to ANSI C; * updated this document with new changes; * updated pull online help page; * added example usage for PC users on how to extract a file using only drag and drop from multi-part mails in Netscape Communicator 4.x email Messenger. Release level: major (out of major, moderate, minor) 1. Introduction This document is for all levels of users. It begins with an overview of the pull. 1.1 What Is the pull pull is a cross-platform software tool used for convenient file extraction and packaging. A single file naming is used for multiple port of pull on Unix, DOS/MS Windows, VMS, and OS/2. The pull can do several things at once. When packing a file, it can compress, split, and/or uuencode the file. When extracting the original file from a compressed, split, and/or file(s), it does the opposite of packing: uudecoding, merging, and decompressing. 1.2 What Are the Major Uses of pull pull can be used for two opposite purposes: file extraction and packaging. For file extraction, it can conveniently extract the original file(s) from * several email files decomposed from a single large file after compress, split, and uuencode; * a compressed and uuencoded file; * a uuencoded file; * several unrelated uuencoded files concatenated in one file; * file(s) compressed by gzip or Unix compress. For file packing, it can in one step * break a large file into several smaller ones for email delivery after compress, split if necessary, and uuencode. Versatile split is provided. * compress and uuencode a file for email delivery. 1.3 On Which Platforms pull Works pull currently works on four major platforms: Unix, DOS/MS Windows, VMS, and OS/2. To elaborate, * Unix is a family of over 60 variants/flavors (67+ listed in http://www.ugu.com/sui/ugu/show?ugu.flavors ); * DOS are MS-DOS (6.22 being the latest and the last), IBM PC DOS (7 being the latest) and a few more MS-DOS compatibles. In the rest of this document, though mostly MS-DOS is mentioned, it does not exclude pull's applicability to other MS-DOS compatible DOSes; * MS Windows includes Windows 3.x, 95, and NT 3.51, 4.0. (CE is the youngest little member in MS Windows family, out of consideration of pull porting for now.) * VMS: VMS and OpenVMS * OS/2: FAT and HPFS as listed in next table. With possible concern on over 60 Unix variants, for Unix users' assurance, pull has been tested under 11 Unix variants explicitly listed in the table and is expected to work on any other unlisted Unix variant as well. Table 1. Platforms on Which pull Works platform variants/flavors SunOS, Solaris, HP-UX, AIX, IRIX, Digital Unix, NeXT, BSD/OS, UNIX Ultrix, QNX, Linux, ... DOS/MS-WIN MS-DOS (6.22), MS Windows 3.x/95/NT, PC DOS (7), MS-DOS compatibles VMS VMS, OpenVMS OS/2 OS/2 FAT, OS/2 HPFS 1.4 In What Ways pull Might Be Used At present, pull is implemented as a Command-Line Interface (CLI) filter application. By properly setting it up in windows environment as described in the sequel, it can perform drag-and-drop, double-click etc. types of operations as a Graphical User Interface (GUI) application. The next table elaborates on how pull might be used in MS Windows, in which "MS-DOS mode" refers to a screen created by directly launching MS-DOS or restarting computer in MS-DOS mode; whereas "MS-DOS window" refers to a window launched by clicking MS-DOS prompt icon or selecting it in Program Menu in MS Windows. Either may be called the MS-DOS box. Again, the listed usage below have all been tested. Table 2. The Ways pull Might be Used in MS Windows Environment Used in Through MS-DOS Windows Windows Windows 3.x 95 NT MS-DOS mode cmd typing/piping y y y y MS-DOS cmd n/a y y y window typing/piping n ? y y MS Windows drag-and-drop n y y y MS Windows double-click 1.5 How pull Works pull packs a file for email delivery and extracts original file from received emails. 1.5.1 Pack A File Packing a file involves three possible stages of processing: * compressing: calls an external compressor such as default gzip or pkzip * splitting: if the compressed file is still too large, or on demand, the compressed file is split in variety of specified ways * encoding: compressed file or split files are encoded with a built-in uue77 encoder. uue77 writes output 77 characters a line vs. conventional uuencoder of 61 char/line. The built-in uue77 encoder is slightly modified from the original Unix uuencode (1983). The sequence of above three stages are predetermined. Which stage or stages the packing will go through might be specified by users. For example, a user may only want to split a huge downloaded file for disk floppy transfer, or perform a simple uue77 encoding. To be meaningful, the packing process has to go through at least one stage. The all possible combinations of packing operations are tabulated below. Note that each individual packing operation has been implemented. It is some of combinations that have not been "unlocked". Table 3. Possible Combinations of File Packing Actions combination compress split encode status possible use 7 (111) y y y available tightly pack email file 3 (011) n y y n/a pack email file 5 (101) y n y available tightly pack email file 6 (110) y y n n/a fit file onto floppy 1 (001) n n y n/a uue77 encode 2 (010) n y n n/a versatile split, for floppy 4 (100) y n n n/a compress in .gz/.zip 0 (000) n n n degenerated does nothing 1.5.2 Extract Original File It is extremely easy for users to extract the original file from the packed files. pull performs the task automatically no matter what stage and how many stages the file packing had gone through. 2. Obtain and Setup pull "obtain" is about getting right version of pull for your platform. "setup" describes compiling, linking, installing, customizing pull for convenient use. In particular, "compile, link, install" here enables pull to be used through the command-line interface; while "customize" enables pull to be virtually a GUI application allowing drag-and-drop, double-click,... type of GUI operations. 2.1 Which Program Files Are Required and Where They Are Archived Table 4. Archived and Executable Pull platform pull archived executable used on pull is xx-bit UNIX pull.c pull all UNIX variants 32, 64 DOS/MS-WIN pull.exe pull.exe DOS, MS WIN 16 3.x/95/NT VMS pull.c pull.exe 32, 64 VMS, OpenVMS OS/2 pull_fat.exe pull.exe 32 pullhpfs.exe pull.exe OS/2 FAT 32 OS/2 HPFS A single source pull.c is developed and maintained. When conditionally compiled on a particular platform/file system, a platform/file system specific pull executable is generated. Please be aware that the four listed pull.exe's are all different but the filename. Choose the one matching your platform. NT pull.exe is for Intel architecture, not for Alpha (64-bit), Mips, and PPC. For OS/2 users who aren't sure of on which file system (FAT or HPFS), please use OS/2 FAT pull.exe. pull can be obtained through ftp ftp://uwalpha.uwinnipeg.ca/pub/fcssc/fhy/HELP/pull.c -- Unix, VMS ftp://uwalpha.uwinnipeg.ca/pub/fcssc/fhy/HELP/pull.exe -- DOS/MS-WIN ftp://uwalpha.uwinnipeg.ca/pub/fcssc/fhy/HELP/pull.zip -- OS/2 FAT, HPFS ftp://ccic.ifcss.org/pub/software/unix/utils/pull.c.gz -- Unix ftp://ccic.ifcss.org/pub/software/dos/utils/pull.exe -- DOS/MS-WIN ftp://ccic.ifcss.org/pub/software/vms/utils/pull.c-gz -- VMS ftp://ccic.ifcss.org/pub/software/os2/utils/pull.zip -- OS/2 FAT, HPFS and CCIC's ftp mirror sites. Web http://ccic.ifcss.org/ftp-pub/software/unix/utils/pull.c.gz -- Unix http://ccic.ifcss.org/ftp-pub/software/dos/utils/pull.exe -- DOS/MS-WIN http://ccic.ifcss.org/ftp-pub/software/vms/utils/pull.c-gz -- VMS http://ccic.ifcss.org/ftp-pub/software/os2/utils/pull.zip -- OS/2 FAT, HPFS Email To obtain the latest version of pull, send an email to "listserv@uwalpha.uwinnipeg.ca" with a one-line command in mail body as below: "help fhy-ps" for Unix and VMS version, or "help fhy-psdos" for DOS/MS-WIN version. Then the listserv "machine" will automatically email you a copy. 2.2 How to Compile and Link pull This subsection only applies to Unix and VMS users. pull DOS/MS Windows and OS/2 users receive the executable pull.exe. Thus no compilation and linking is required. 2.2.1 On Unix Platforms Let ">" be Unix command prompt. Compile pull.c to pull with >cc -o pull pull.c The compilation is successful if no error message or only with warning message. In later case, you may send the complete warning message to me for code improvement. Or, with optimization >cc -O -o pull pull.c It might produce a smaller and more efficient executable. But it usually takes longer time to compile and possibly fails to compile. If fails, go back to simple approach above. Wondering if what cc is doing during "long" compiling period? Try >cc -v -o pull pull.c In case cc compiler is not on your system, next try GNU C compiler. Substitute "gcc" to "cc" in above commands. Finally, you may confirm if it works with >pull -h that gives pull's on-line main help page. 2.2.2 On VMS Platforms Compile and link pull.c for VMS version Let ">" be VMS command prompt. 1. Specify I/O >define lnk$library sys$library:vaxcrtl 2. Compile pull.c to pull.obj >cc pull /define=(VMS_PULL) where VMS_PULL must be in upper-case. The compilation is successful if no error message or only with warning message. In later case, you may send the complete warning message to me for code improvement. 3. Link pull.obj to pull.exe >link pull 4. Set symbol for pull.exe >pull == "$disk:[directory]pull.exe" 5. Clean Up >delete pull.obj;1 6. For confirmation, display on-line main help page. >pull -h Note: after step 4, pull is ready for use. BUT it only works for current terminal (login) session. To make it work for every login session as a system command, do "installation" described next. 2.2.3 On DOS/MS Windows Platforms No compilation is required. For your reference, if use Turbo C++ compiler you may compile pull.c to pull.exe by issuing >tcc -DMSDOS_PULL=1 pull 2.2.4 On OS/2 Platforms No compilation is required. For your reference, if use Borland C++ compiler you may compile pull.c to pull.exe by issuing on FAT file system >bcc -DOS2FAT_PULL=1 pull.c on HPFS file system >bcc -DOS2HPFS_PULL=1 pull.c 2.3 How to Install pull The purpose of installation here is to enable you to conveniently use pull as a system command in command-line interface environment. 2.3.1 On Unix Platforms There are two options: a) Move pull to your "bin" directory. Then it can be used from any directory. If you don't have "bin" directory, a-1) at your home dir, issue "mkdir bin" -- creates "bin" under your home directory; a-2) edit one of your login profiles such as .cshrc or .login file by adding bin to search path, i.e., add a line set path = ($path /absolutePathToYourHome/bin) or alike; To get the value of "absolutePathToYourHome", issue "cd" or "cd ~/" to return to your home directory. Then issue "pwd". Finally, it might look something like: set path = ($path /users/group3/john/bin) a-3) logout then login (for once only). This is a safe way, but slow. Or you may issue "source .cshrc" or "source .login" in each window you'll use pull if you are in window system. b) Define an alias of pull in your .cshrc file pointing to where pull resides Once all done, to save disk space, you might remove pull.c 2.3.2 On MS Windows Platforms First, put PULL.EXE under C:\BIN directory, or any directory you like. Then add the directory path into C:\AUTOEXEC.BAT file, such as PATH=C:\BIN or append it to an existing one PATH=C:\DOS;C:\BIN When pull involves compress/decompress operation, it calls an external utility gzip. This requires gzip also installed as a DOS command or at least under the same directory. For gzip, from ftp you may get gzip.exe and gzip386.exe. gzip386.exe runs faster. pull.exe uses one of them, and must be named as gzip.exe. To have better performance, use gzip386.exe and rename it to gzip.exe. Please note this gzip386.exe works on Win3.x and 95, but not on NT. For NT user, look for NT version of gzip.exe that also works on Win95. Before proceed further, open a MS-DOS box. Issue "gzip -h" there to confirm gzip works. If not, such as encountered "Abnormal program termination", you've got a wrong version. Having completed the above step, there are two options. The first supports the full power of pull. The second gives drag-and-drop and double-clicking types of conventional window application convenience, as described in next subsection. Use pull in MS-DOS Command-Line Interface First open an MS-DOS window/box, such as a native MS-DOS 6.22 box, or an MS-DOS Prompt window launched from Windows 3.x/95/NT, or start with MS-DOS mode. Then inside DOS window/screen, issue pull commands, see "pull -h". This approach allows every feature of pull to be realized. 2.3.3 On VMS Platforms Place following line in your LOGIN.COM file pull=="$disk:[directory]pull.exe" Modify disk and directory appropriately to point to pull.exe. If you don't have LOGIN.COM file, you can create one. Once all done, to save disk space, you might delete pull.c 2.3.4 On OS/2 Platform First, put PULL.EXE under C:\BIN directory, or any directory you like. Then add the directory path into C:\CONFIG.SYS file, such as PATH=C:\BIN or append it to an existing one. When pull involves compress/decompress operation, it calls an external utility gzip. This requires gzip also installed as a system command or at least under the same directory with pull. Having completed the above step, there are two options. The first supports the full power of pull. The second gives drag-and-drop and double-clicking types of conventional window application convenience, as described in next subsection. 2.4 How to Customize pull as A Window Application This subsection discusses methods to enable pull for drag-and-drop, double-click windows operations. In general, the drag-and-drop feature requires to create an icon of pull on desktop/workspace so dragged file(s) can be dropped upon the icon. The double-click feature requires to register the file extension such as ".pul" with windows and associate it with an application such as pull. 2.4.1 On Unix Platforms It is largely Unix variant dependent. 2.4.2 On MS Windows Platforms For MS Windows, Windows 95 and NT 4.0 have the similar "look and feel"; whereas NT 3.51's is more similar to Windows 3.x's. Some discussions in this section are organized along these two groups. 2.4.2.1 Customize pull for Drag and Drop GUI Operation The basic idea is to create an icon shortcut to pull on desktop. To extract or pack the file, simply drag a file or several files and drop it/them onto the pull icon. pull will automatically do the rest. No MS-DOS window requires to be opened first. No pull commands need to be entered in command line. Here are steps to set up pull icon on desktop. Assume that PULL.EXE is placed under directory C:\BIN Windows 95 and NT 4.0 Step 1. Create shortcut icon to pull.exe on desktop Through Window (NT) Explorer or "Start | Find -> Files or Folders", navigate down or search for PULL.EXE. Select it Click it with right mouse button, drag it onto desktop while holding the right mouse button. Click "Create Shortcut(s) Here" with left mouse button. An MS-DOS icon of "Shortcut to Pull.exe" name is created. Internally, a program information file (PIF) is created that optimize the DOS environment for pull. Next we want to customize pull's PIF for our convenience using GUI. Step 2.1 Modify the icon property for file extraction Click icon name to change it to "Pull 3.3" or the current version number if v.3.3 is not the current. Right mouse button click on pull icon, select "Properties" in pull-down menu. Select "Program" Click "Change Icon..." button in bottom-right. Change the icon from MS-DOS one to any one else you like since the window the pull.exe icon corresponds to is different from the MS-DOS Prompt window. Still in Program box, "Working" field lists the working directory where pull output file is to be placed. So change it to C:\TEMP, assume you have a C:\TEMP directory. The text field containing "PULL.EXE" on top besides the icon is the window name when launched in future. Change it to "PULL output to C:\TEMP". It reminds you later where the pull output file is. Deselect (empty) "Close on exit" check box under text fields. After pull execution, the inactive pull window remains and contain pull working message. (Later after you become familiar with pull, you might check this box to save a step of closing pull window.) Click "Apply" and "OK" to finish pull icon setup. An alternative to above configuration is to leave "Working" filed empty so pull output file is directly placed on desktop. (You need to clean up desktop later.) And check "Close on exit" check box, so after file dropped on pull icon and "pulling" down the pull window is closed by itself. Step 2.2 Modify the icon property for file packing To make use of the other half of pull feature--file packing, another icon may be created as above and modified in addition as following. Change icon name to "Pull -d 3.3" or "Push 3.3" Append pull command option "-d", not "-D", into "Cmd line" field as "C:\BIN\PULL.EXE -d". Please note that the "Push" icon only works for NT 4.0, not for Windows 95. On Windows 95, "-d" is ignored, that is, "PULL.EXE -d" is treated as "PULL.EXE". (If you find the work-around, let me know.) Windows 3.x and NT 3.51 As a remark, drag-and-drop operation is not limited to drop a file on a shortcut icon. Dropping a file on PULL.EXE listed in Windows/NT Explorer works as well. The price? need to navigate to PULL.EXE. Besides, as you can imagine, the way to configure a shortcut icon of a filter type DOS application such as pull icon is very flexible. 2.4.2.2 Customize pull for Double-click GUI Operation The double-click operation refers to by double-clicking a file, pull is automatically launched extracting or packaging the file. The idea is to associate the file name extension with the application in Windows, in other word, register a file type with an application in Windows. Therefore once a file with this type of extension is double-clicked, Windows launches the associated application. Windows 95 and NT 4.0 From Windows (NT) Explorer, navigate to C:\BIN and select PULL.EXE Click "View | Options...| File Types | New Type..." (Or from "Control Panel', click "Internet | Programs | File Types... | New Type...".) From "Add New File Type" dialog box, fill "Description of type" text entry field up with "compressed/split/encoded". put either ".pul" or ".cse" in text entry field "Associated extension". "pul" stands for "pull', easy to memorize. ".cse" stands more accurately for "compressed/split/encoded", or for Computer and Systems Engineering:) Click "Change Icon..." button on top. Select a favorable icon for this new type, ideally choose identical one with the pull shortcut icon on desktop. Click "New..." button under big "Actions:" box. A "New Action" box pops up. Branch 1. Link to pull icon to do file extraction Place "Extract file with Pull 3.3" in "Action" text entry field. Click "Browse...". An "Open With..." window pops up. Default "Look in" directory is "Desktop". Find and select "Pull 3.3". Double-click it. Click "Open" button. "Pull 3.3.pif" file is selected. Click "OK" button in "New Action" window. Branch 2. Link to pull -d icon to do file packaging Place "Package file with Push 3.3" in "Action" text entry field, assuming "Push 3.3" icon has been created earlier. Click "Browse...". An "Open With..." window pops up. Default "Look in" directory is "Desktop". Find and select "Push 3.3". Double-click it. Click "Open" button. "Push 3.3.pif" file is selected. Click "OK" button in "New Action" window. (Branches merged) Click "Close" in "Add New File Type" window. Click "Close" in "File Types" window Click "OK" in "Internet Properties" window. Remark: In above new file type is linked to pull icon on desktop. The other way is to directly link file type to C:\BIN\PULL.EXE Since pull can extract uuencoded, gzip compressed, Unix "compress" compressed file, you may associate .uue, .gz, .Z with pull one by one. Windows 3.x and NT 3.51 In File Manager, you can drag a gzip/split/uue file and drop it over PULL.EXE for file extraction. To use double-click feature, you need do following. Step 1. Create a PIF file for pull.exe From Program Manager, Main launch PIF Editor. An PIF Editor window pops up. Fill up following: Program Filename: C:\BIN\PULL.EXE Window Title: Pull 3.3 (output to C:\TEMP) Start-up Directory: C:\TEMP (if you don't have directory TEMP, create one.) Deselect (empty) check box Close Window on Exit at bottom-left. To save, click File | Save As... Directory: C:\PULL, File Name: pull.pif Then File | Exit PIF Editor - PULL.PIF window. Step 2. Associate file *.PUL with PULL.PIF (PULL.EXE) From File Manager, locate C:\PULL\PULL.PIF, select it. Click File | Associate... An "Associate" window pops up. Fill up Files with Extension: PUL Click Browse... till locate C:\PULL\PULL.PIF and select it. Click OK exiting Associate window. Remark: The purpose of Step 1 is to create an inactive pull window that displays pull working message after pull completes. This may not be necessary if you know where pull places its output file. If so, only do Step 2. In it, associate .PUL directly with C:\PULL\PULL.EXE. To use it, double-click a file FOO.PUL. To make pull works for another file extension, repeat the association with that extension. 2.4.3 On OS/2 Platform pull can be configured for double-click and drag-and-drop operations. 2.4.3.1 Double-Click Double clicking on a data file icon whose extension/suffix already associated with pull will launch pull.exe and extract the original file. Take OS/2 v3 for example. To set up pull for double-click operation, in "Icon View", click "Drives | Drive C | directory PULL | file PULL.EXE", assuming pull.exe is at C:\PULL\PULL.EXE. In "PULL - Icon View", select PULL.EXE with left mouse button. Clicking mouse button 2 pops up a menu. Select "Settings". "PULL.EXE - Settings" notebook pops up. Do following: Program tab "Path and file name:" already filled up with "C:\PULL\PULL.EXE" Working directory: C:\PULL Session tab Check "OS/2 window" Uncheck "Close window on exit" Association tab Select "Plain Text", "Add >>" it to "Current types". Create "New name: *.UUE", "Add >>" it to "Current names". Create "New name: *.ZUE", "Add >>" it to "Current names". Window tab Do nothing. General tab Change default "Title: Program" to "pull". 2.4.3.2 Drag and Drop Drag one or several data file icons and drop on pull.exe icon. Pull is launched and extract the original file. To set up, From Icon View window, use mouse button 2 drag PULL.EXE icon to desktop while holding Ctrl key. An icon PULL.EXE is created on desktop. Click this icon with mouse button 2; select Settings. PULL.EXE Settings Notebook pops up. Tab settings are similar to above except that do not associate any file types with pull so any data files can be dropped onto pull icon. To do drag and drop, select a data file icon with mouse button 1, then 2, then "Pickup". Click pull icon on desktop with mouse button 2, then "Drop". Or using mouse button 2 drag a file to pull icon while holding Crtl key. Release Ctrl key. Drop it. To do several files once, select file one by one while holding Crtl key. Use mouse button 2 to pickup and drop them on pull icon. For each data file, a pull session is launched. Unfortunately, we want only one pull session launched for all files dropped onto it, instead. 3. Usage pull performs two opposite types of operation: file extraction and packaging. In addition, pull includes a rich set of two level on-line help pages. It is called page because each command help option gives up to one-screenful, i.e., a page, of help information, not to be confused with a web page. usage: pull [-hBCDGILSUV] [-cqs] file(s) [-cqs] -- on VMS [-cqs] [- < file(s)] [> outfile] -- on Unix, DOS, and OS/2 -d[cq] [-b bytes] [header] file -d[cq] [-p parts] [header] file -d[cq] -f [-b bytes] file -d[cq] -l [-b bytes] file -d[cq] -n [header] file 3.1 Extracting Extract the original file(s) from uuencoded/split/compressed raw file(s). 3.1.1 Jointly Extracts a single file by combining a set of compressed/split/encoded files that can be in arbitrary sequence. pull file1 file2 file3 ... pull metafile where a "metafile" is a filename containing meta-chars (wild card): *, ?, and [...], [!...] -- on Unix *, ? -- on DOS, OS/2 *, % -- on VMS. where "*" matches zero or more chars. "?" and "%" matches any single char. "[...]" matches a char in the specified range. "[!...]" matches a char outside the specified range. Before actual extraction took place, the meta-filename is expanded to a list of filenames by system command shell, or by the application, depending on the operating system. pull catfile where a "catfile" is a single file in which several encoded files are concatenated. 3.1.2 Separately Extract files independently from several files. No file merging. pull -s file1 file2 ... pull -s metafile pull -s catfile 3.1.3 Standard I/O (Filter) Standard I/O option can be combined with other command options for file extraction as well as packaging. It renders pull the power as a filter application for command piping, GUI drag-and-drop, double-click... Read from stdin/terminal Unix, DOS, OS/2: pull [-] VMS: pull Send to stdout/terminal Unix, DOS, and OS/2 only. pull -c file 3.1.4 Suppress Verbose pull -q file Works silently. Apply to file packaging as well. 3.2 Packaging Packs file by compress, split, and encode. "De" pull = push. 3.2.1. One Input File pull -d [-fln -b bytes -p parts] file -d file: equal size split, up to default 64k/chunk. Default 64k approximates the mail size limit set by some mail servers, if set at all. 1 K = 1024 bytes here, not 1000 bytes that most storage manufactures use. -d -n file: no split -d -b bytes file: equal size split, up to "bytes"/chunk, or "octets" if you are more academic. -d -p parts file: equal size split, into number of "parts" (1--9) -d -f [-b bytes] file: first file aligned split. -d -l [-b bytes] file: last file aligned split. First/Last N-1 files has chunk size "bytes" or default 64k each. The N'th file takes the remaining size. 3.2.2 Two Input Files pull -d [-n -b bytes -p parts] header file Ascii "header" file with arbitrary filename is prepended intact to the first part of output files. All output parts are of equal size in bytes. -d header file: equal size split, up to default 64k/chunk -d -n header file: no split -d -b bytes header file: equal size split, up to "bytes"/chunk -d -p parts header file: equal size split, into number of "parts" (1--9) 3.3 On-line Help Pages To display help pages, issue "pull [-hBCDGILSUV]". On VMS, double-quotes are required for an upper-case option, e.g. pull "-V". -h : main help page -I : installation -B : bug report and comment -L : license -C : compilation and link -S : PostScript file viewing and printing -D : "de" pull, packing file -U : usage examples -G : gzip/gunzip archive information -V : version number 4. Typical Usage Examples This section provides some typical usage examples for file extraction and packaging. Instantiated Unix flavor filename "foo", "bar" may be used in examples. 4.1 Extracting Examples are listed in subsections along the platforms: Unix, DOS/MS Windows, VMS, and OS/2. 4.1.1 On Unix a) To extract foo9508a.ps from 4 received mails, use one of methods below a-1) without saving file(s), from your mailer, pipe the ps mails to pull; Example 1. in Elm, press "t" to tag the ps mails one by one; then from one of tagged mails, press "|"; then issue "pull", "pull -c > foo.ps", or "pull -c | lpr -prtname" to extract, extract to file, to printer. Example 2. in "mail" prompt &, "| 5-8 pull" pipes mails 5-8 to pull. a-2) append received mails, in any order, onto one file, say foo.uue. For example if Netscape 3.x or Communicator 4.x mailer is used, click on 4 mails while holding Control key. Click "File | Save As..." to default file type ".html" and file name "untitled.html". Issuing "pull foo.uue" or "pull untitled.html" extracts foo9508a.ps. Issuing "pull foo.uue" extracts foo9508a.ps a-3) save received mails in 4 separate files: foo1, foo2, foo3, and foo4. Assume foo1, foo2, foo3, foo4 uudecoded to foo9508a.sz1, ...foo9508a.sz4 - "pull foo?": "?" matches any single char - "pull f*": "*" matches zero or more chars - "pull foo[1-4]": matches exactly files foo1, foo2, foo3, and foo4. In above sub-usages, if irrelevant filenames are expanded, pull will quit. In sub-usages below, the order of input files may be arbitrary. - "pull foo1 foo2 foo3 foo4" - "pull foo4 foo9508a.sz1 foo2 foo9508a.sz3", in mixed formats. - "pull foo9508a.sz1 foo9508a.sz2 foo9508a.sz3 foo9508a.sz4". b) To extract foo9508a.gb or foo9508a.bg5 from received mail, issue "pull foo.uue", assuming the mail saved in file "foo.uue" c) To decompress, "pull foo.gz" or "pull foo.Z" 4.1.2 On MS Windows and DOS On MS Windows a) Double-click Assume the raw file to be extracted had the extension already registered in Windows and associated with the pull. The extensions might be .PUL, .UUE, .CSE, etc. Locate the file, double click on the file. Pull is invoked performing file extraction. To extract foo9508a.ps from four received mails, first concatenate them into one file in arbitrary sequence. It often can be done at the time saving emails to file. For example if Netscape 3.x or Communicator 4.x mailer is used, click on 4 mails while holding Control key. Click "File | Save As..." to file name "foo.pul". Then double clicking file "foo.pul" extracts foo9508a.ps. b) Drag and Drop Drag and drop does not require file extension registered. In addition, several files can be dragged and dropped at once. Locate the raw file with Windows Explorer, NT Explorer, or File Manager. Drag and drop it on Pull icon on desktop (may not applicable to Windows 3.x), or directly on PULL.EXE file (applicable to all). To select a group of files, click them while holding Control key or Shift key. Holding Shift key limits selection to adjacently listed files. Drag and drop may be possible when using a mailer. Take Netscape Communicator 4.x mailer Messenger for example, if four-part received mails each is through mail file attachment, open the mail; click the paper clip icon at upper-right corner. It converts the attached file to a file icon in the same mail window. Drag this file attachment icon and drop it onto desktop. It creates another file icon on desktop. Repeat the process till all four mail attachments have been dragged and dropped onto the desktop. Then select all four file icons. Drag and drop them together onto the pull icon on desktop. foo9508a.ps will be extracted out of these four-part files. If there is only one mail attachment to be extracted using Communicator mailer, can you drag the mail file attachment icon and drop it on top of desktop pull icon? Of course, you can. But nothing happens. You have to first drop it onto desktop, then drag and drop it onto pull icon. It all depends on how capable your email client is. Ideally, drag and drop should work similarly for listed mails in a mail client window and for listed files in Window Explorer window. Inside An MS-DOS Box a) To extract foo9508a.ps from 4 received mails, use one of methods below a-1) without saving file(s), from your mailer, pipe the ps mails to pull; a-2) append received mails, in any order, onto one file, say foo.uue. Issuing "pull foo.uue" extracts foo9508a.ps a-3) save received mails in 4 separate files: foo1, foo2, foo3, and foo4. Assume foo1, foo2, foo3, foo4 uudecoded to foo9508a.sz1, ...foo9508a.sz4 - "pull foo?": "?" matches any single char - "pull f*": "*" matches zero or more chars In above sub-usages, if irrelevant filenames are expanded, pull will quit. In sub-usages below, the order of input files may be arbitrary. - "pull foo1 foo2 foo3 foo4" - "pull foo4 foo9508a.sz1 foo2 foo9508a.sz3", in mixed formats. - "pull foo9508a.sz1 foo9508a.sz2 foo9508a.sz3 foo9508a.sz4". b) To extract foo9508a.gb or foo9508a.bg5 from received mail, issue "pull foo.uue", assuming the mail saved in file "foo.uue" c) To decompress, "pull foo.gz" or "pull foo.Z" 4.1.3 On VMS a) To extract foo9508a.ps from 4 received mails, use one of methods below a-1) without saving file(s), from your mailer, pipe the ps mails to pull; a-2) append received mails, in any order, onto one file, say foo.uue; Issuing "pull foo.uue" extracts foo9508a.ps a-3) save received mails in 4 separate files: foo1.uue, ..., foo4.uue. Assume foo1.uue, ..., foo4.uue uudecoded to foo9508a.sz1, ...foo9508a.sz4 - "pull foo%.uue": "%" matches any single char, - "pull f*.uue": "*" matches zero or more chars In above sub-usages, if irrelevant filenames are expanded, pull will quit. In sub-usages below, the order of input files may be arbitrary. - "pull foo1.uue foo2.uue foo3.uue foo4.uue". - "pull foo4.uue foo9508a.sz1 foo2.uue foo9508a.sz3", in mixed formats. - "pull foo9508a.sz1 foo9508a.sz2 foo9508a.sz3 foo9508a.sz4". b) To extract foo9508a.gb or foo9508a.bg5 from received mail, issue "pull foo.uue", assuming the mail saved in file "foo.uue" c) To decompress, "pull foo.gz" or "pull foo.Z" 4.1.4 On OS/2 a) To extract foo9508a.ps from 4 received mails, use one of methods below a-1) without saving file(s), from your mailer, pipe the ps mails to pull; a-2) append received mails, in any order, onto one file, say foo.uue. Issuing "pull foo.uue" extracts foo9508a.ps a-3) save received mails in 4 separate files: foo1, foo2, foo3, and foo4. Assume foo1, foo2, foo3, foo4 uudecoded to foo9508a.sz1, ...foo9508a.sz4 - "pull foo?": "?" matches any single char - "pull f*": "*" matches zero or more chars In above sub-usages, if irrelevant filenames are expanded, pull will quit. In sub-usages below, the order of input files may be arbitrary. - "pull foo1 foo2 foo3 foo4" - "pull foo4 foo9508a.sz1 foo2 foo9508a.sz3", in mixed formats. - "pull foo9508a.sz1 foo9508a.sz2 foo9508a.sz3 foo9508a.sz4". b) To extract foo9508a.gb or foo9508a.bg5 from received mail, issue "pull foo.uue", assuming the mail saved in file "foo.uue" c) To decompress, "pull foo.gz" or "pull foo.Z" 4.2 Packaging To split foo9508a.ps into multiple emailable parts of equal size in bytes: *"pull -d header foo9508a.ps" creates 4 mails, "header" prepended to mail 1. "header" is a pre-edited text introduction message for the mail. *"pull -d foo9508a.ps" creates 4 sendable mails To uuencode file in 77-char line, issue "pull -d foo9508a.gb" or "pull -d foo9508a.bg5" 5. Other Related Topics 5.1 Exit Code 0: normal >0: abnormal 5.2 Internally Supported Filename Extensions To achieve the cross-platform transparency, pull uses 8.3 file naming convention from DOS as the common denominator. The filename extension of three alphadigits is used for conveying file attribute information of file type, compressor type, part number for files before uuencoding. (What name of a uuencoded file might be is irrelevant to the file extracting process of pull.) When a file is packaged using "pull -d foo", the filename extension is processed and transformed according to pull internal file naming specification. At recipient side, based on transformed filename extension(s), pull is able to extract original file correctly. In addition, it will restore the original filename provided that the original file is one of the following types: .ps .pdf .gif .jpg .gb .bg5 .mpg .eps .fps .c .p .exe .doc .txt and possibly compressed with gzip, pkzip, or Unix Compress. If a file does not have the above listed extensions or no extension at all, pull can still be used to package the file properly and extract the original file correctly. But the name of the extracted original file will have no extension. The above listed filename extension can also be in upper case or even mixed-case if the host Operating System file naming is case-insensitive. Among three listed compressors above, only support to gzip in pull is thoroughly tested, that is, guaranteed. pkzip has a version compatibility issue and it's not widely installed on Unix machines. Support to Unix .Z Compress in pull is to be phased out following its own lead in Unix world. pull is capable to support maximum 36 file types with which the extension of the original filename can be restored. The above filename extension list will be expanded as needed. 5.3 gzip Archive Information pull uses gzip/gunzip that is stored at anonymous ftp sites (for Unix, MS-DOS, OS/2, VMS, Mac, Atari, Amiga, Primos): prep.ai.mit.edu:/pub/gnu/gzip-1.2.4.tar (or .shar or .tar.gz : source) prep.ai.mit.edu:/pub/gnu/gzip-msdos-1.2.4.exe (MSDOS, lha self-extract) garbo.uwasa.fi:/unix/arcers/gzip-1.2.4.tar.Z (source) garbo.uwasa.fi:/pc/unix/gzip124.zip (MSDOS exe) ftp.uu.net:/pub/archiving/zip/VMS/gzip124x.vax_exe (VMS exe) mac.archive.umich.edu:/mac/util/compression/macgzip0.22.cpt.hqx (Mac) src.doc.ic.ac.uk:/computing/systems/mac/info-mac/cmp/mac-gzip-022.hqx mac.archive.umich.edu:/mac/development/source/macgzip0.2src.cpt.hqx To get NT versions (Intel, Mips, Alpha) of gzip.exe, search http://www.shareware.com for NT version of gzip. Reference: Usenet Newsgroup comp.compression FAQ Part 1 stored at: rtfm.mit.edu:/pub/usenet/news.answers/compression-faq/part[1-3] 5.4 Viewing and Printing PostScript Files 5.4.1 Viewing A PostScript File Need a ps interpreter and a previewer. They are widely available as freeware. Unix: check "pageview" on Sun, "ghostview" on HP, etc. MS-WIN, OS/2: GSview and Aladdin Ghostscript; VMS: GhostView-VMS. Check info at ftp://ftp.cs.wisc.edu/ghost/gsfaq.txt http://www.cs.wisc.edu/~ghost/gsfaq.html Mac: ftp://ftp.cs.wisc.edu/pub/ghost/aladdin/mac/ http://www.glyphic.com/glyphic/projects/macgs.html Ghostscript, Ghostview and GSview Home page: http://ftp.cs.wisc.edu/~ghost/ For more information on ps viewers and ps file, you may read the FAQ of Usenet newsgroup comp.sources.postscript (also available from ftp://wilma.cs.brown.edu/pub/comp.sources.postscript) 5.4.2 Printing A PostScript File Printable on the PostScript laser printer, or a personal laser printer plus a PostScript interpreter such as Ghostscript. 5.5 uue77 Encoder The conventional uuencoder writes output 61 chars/line. uue77 encoder writes 77 chars/line. By doing so, it cuts number of lines by 20%. uue77 encoder is modified from the original pair of uuencode/uudecode developed by Regents of the University of California in 1983. Conventional uudecoders can decode the file encoded by uue77. pull.c includes uue77 and uudecode pair. 6. License, Copyright, and Warranty Author: Yao LI Copyright (c): 1995-1997 For user's convenience, uuencode.c and uudecode.c are trimmed and included with the key change to uuencode.c of widening the output from 61 chars/line to 77 chars/line. These two utilities have Copyright (c) 1983/1993 Regents of the University of California. This software is provided "as is" without any warranty; without even the implied warranty of merchantability. Redistribution and non-commercial use are permitted. 7. Troubleshooting 8. Bug Report and Comments Send the bug report to me (Yao LI) at "ah163@freenet.carleton.ca". Please include - platform: Unix, MS-DOS, Windows, VMS, or OS/2? - file system: if on OS/2, is it FAT or HPFS? - problem description: complete error/warning msg displayed on your screen, including command option, file names in command line - the version number of pull, if obtainable, issue command pull -V -- for Unix, DOS, and OS/2 pull "-V" -- for VMS - operating system and version/release number, C compiler if used on Unix, command "uname -a" displays OS, platform, ... Your comments are always welcome. 9. History The first release -- pull 1.0 was made on Feb. 10, 1995 In all, 18 releases had been made before this release: * 1.0-1.4 (5) in Unix Bourne shell * 2.0-2.9 (10), 3.0-3.2(3) in C 10. Acknowledgments VMS porting received help from W.M. (Canada) and Seak (France). 11. References *"FAQ of Pull and FHY-PS Lists" at ftp://uwalpha.uwinnipeg.ca/pub/fcssc/fhy/HELP/ps_faq.html ftp://uwalpha.uwinnipeg.ca/pub/fcssc/fhy/HELP/ps_faq.txt