gtpm2m2jMigration Guide: Program Update Tapes

File System Tools (APAR PJ27277)

The following section discusses the migration considerations for file system tools.

Prerequisite APARs

See the APEDIT for APAR PJ27277 for information about prerequisite APARs.

Functional Overview

File system tools expands the support provided with TPF Internet server support (TPF Internet Server Support (APARs PJ25589 and PJ25703)) by making it easier to port and create new applications and scripting languages on the TPF 4.1 system. Specifically, file system tools gives you the ability to do the following:

Note:
Practical Extraction and Report Language (Perl) is an example of a scripting language that you can use on the TPF 4.1 system. Information about Perl is available at:
http://www.perl.com

Activating Scripts and Segments from the Command Line
The ZFILE command allows you to run scripts and TPF segments from the command line. The hash-bang symbol (#!) must be on the first line of the script file and indicates that what follows is either the file system file containing the script you want to activate or the 4-character name of the segment you want to activate.

See TPF Operations for more information about the ZFILE command.

Pipe Support
A vertical bar (|), or pipe, is used to connect ZFILE commands. Two or more commands can be connected by placing a vertical bar between each of the commands to form a pipeline. The pipe passes the standard output (stdout) from the first command to the second command as standard input (stdin). This implementation of pipes is limited to ZFILE commnds. See TPF Operations for more information about pipe support that is specific to each ZFILE command.

ZFILE Commands
The family of ZFILE commands is expanded to support web hosting and scripting languages. In addition, the 11 new ZFILE command as provide you with better control over the file system. See TPF Operations for information about ZFILE commands.

tpf_fork Enhancements
The tpf_fork function has been enhanced to allow you to specify how to pass a string of data. The tpf_fork function creates a child process on a specified I-stream by inheriting the environment list, file descriptors, user IDs, working directories, and file mode creation masks of the parent process. Enhancements to tpf_fork allow you to create applications that emulate the execl, execlp, execv, and execvp POSIX functions. See the TPF C/C++ Language Support User's Guide for more specific information about tpf_fork enhancements.

Quoting Mechanisms
The ZFILE commands have been enhanced through the implementation of three quoting mechanisms. The escape character (\), single quotes (' '), and double quotes (" ") provide you with the ability to preserve the literal meaning of certain characters rather than the special meaning that the character would take on otherwise. See TPF Operations for more information about the ZFILE commands and the use of quoting mechanisms.

Architecture

The ability to port and create new applications and scripting languages is enhanced through the implementation of the ZFILE parser, or the CFIX dynamic load module (DLM), and the enhancements made to the tpf_fork function.

CFIX
The CFIX DLM was developed as a shell to parse the ZFILE commands prior to activating the appropriate file system utility. In addition, file system utilities are now invoked uniformly by ZFILE commnds, calls from tpf_fork, and scripting languages. The CFIX DLM provides the processing behind script and segment activation from the command line, using a vertical bar (|) as a pipe, and using quoting mechanisms to escape the special meaning of specific characters.

tpf_fork
The tpf_fork function has been enhanced to pass application-defined environment variables to the child process as well as strings of data passed as arguments through the argv parameter to the main function of the child process. Data passed to the argv parameter can be grouped with quotes to override the default behavior of the tpf_fork function. Typically, this means that a call to tpf_fork will include data to direct the behavior or to provide input for the child process, which has been parsed into single words and passed in the argv parameter array. For example when a user enters ZFILE rm -r testdir on the command line, the ZFILE parser (CFIX) will issue a tpf_fork function call to enter the rm file system utility (segment CFID) with the following parameters passed to the main function of CFID:


argv[0] = rm
argv[1] = -r
argv[2] = testdir

Operating Environment Requirements and Planning Information

There are none.

Interface Changes

The following section summarizes interface changes.

C/C++ Language

The following section summarizes C/C++ language changes. This information is presented in alphabetic order by the type of C/C++ language information. See the TPF C/C++ Language Support User's Guide and TPF Application Programming for more information about C/C++ language.

Build Scripts

Table 851 summarizes changes to the build scripts used by the build tool. This information is presented in alphabetic order by the name of the build script.

Table 851. Changes to Build Scripts for File System Tools

Build Script Type New, Changed, or No Longer Supported? Description of Change
CFIMBS DLM Changed Removed CGLOBB40, which is no longer required by the CFIM member (object file).
CFIPBS DLM Changed Removed I$MSG40 and added CGETOP40.
CFIRBS DLM Changed Removed I$MSG40, which is no longer needed.
CFIVBS DLM Changed Removed I$MSG40, which is no longer needed.
CFIXBS DLM New Build script for the processing of ZFILE commands by the ZFILE parser.
CFJABS DLM New Build script for the ZFILE tr command.
CFJEBS DLM New Build script for the ZFILE export and ZFILE unset commands.
CFJFBS DLM New Build script for the ZFILE find command.
CFJGBS DLM New Build script for the ZFILE grep command.
CFJHBS DLM New Build script for the ZFILE hex command.
CFJPBS DLM New Build script for the ZFILE ps command.
CFJSBS DLM New Build script for the ZFILE sed command.
CFJTBS DLM New Build script for the ZFILE tee command.
CFJXBS DLM New Build script for the ZFILE xargs command.
CISOBS DLM Changed Extended C environment support.

Dynamic Load Module (DLM) Stubs

There are no changes.

General Use C/C++ Language Header Files

Table 852 summarizes the general use C/C++ language header file changes. This information is presented in alphabetic order by the name of the general use C/C++ language header file.

General use means these header files are available for your use.

Table 852. Changes to General Use C/C++ Language Header Files for File System Tools

C/C++ Language Header File New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
param.h Changed No
stdlib.h Changed No
sysapi.h Changed Yes. Recompile programs that call the tpf_fork function.

Implementation-Specific C/C++ Language Header Files (IBM Use Only)

Table 853 summarizes the general use C/C++ language header file changes that are for IBM use only. This information is presented in alphabetic order by the name of the general use C/C++ language header file.

Table 853. Changes to Implementation-Specific C/C++ Language Header Files (IBM Use Only) for File System Tools

C/C++ Language Header File (IBM Use Only) New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
c$proc.h Changed No
cenvir.h New No
i$argv.h New No
i$cmds.h New No
I$Dir.hpp Changed No
I$Env.hpp Changed No
I$File.hpp Changed No
i$find.h New No
i$hex.h New No
I$Msg.hpp No Longer Supported No
i$ps.h New No
i$sed.h New No
i$sfct.h New No
i$sh00.h New No
i$sh01.h New No
i$sh02.h New No
i$sh04.h New No
i$sh05.h New No
i$sh06.h New No
i$sh07.h New No
i$sh08.h New No
i$sh09.h New No
i$sh10.h New No
i$sh11.h New No
i$sh12.h New No
i$sh13.h New No
i$sh15.h New No
i$sh16.h New No
i$sh17.h New No
i$sh18.h New No
i$sh19.h New No
i$sh20.h New No
i$sh22.h New No
i$sh23.h New No
i$sh24.h New No
i$sh25.h New No
i$tr.h New No
I$ZF.h Changed No

Library Interface Scripts

Table 854 summarizes changes to the library interface scripts used by the library interface tool and the build tool. This information is presented in alphabetic order by the name of the library interface script.

Table 854. Changes to Library Interface Scripts for File System Tools

Library Interface Script New, Changed, or No Longer Supported? Description of Change
CISOXV Changed Extended C environment support.

Library Members (Object Files)

Table 855 summarizes the library member (object file) changes. This information is presented in alphabetic order by the name of the library member (object file).

Table 855. Changes to Library Members (Object Files) for File System Tools

Library Member (Object File) Library Module Name New, Changed, or No Longer Supported? Type Description of Change
CENVIR CISO New C Language Enhanced environment variables.
CFORKA COMX Changed Assembler Enhanced main function support.
CFORKC COMX Changed C Language Enhanced main function support.
CLMINT CISO Changed Assembler Enhanced environment variables.
CPRSMA CISO Changed C Language Enhanced main function support.
CPWGR0 COMX Changed C Language Modified by file system tools.
CSETNV CISO Changed Assembler Enhanced environment variables.
CUNSTV CISO Changed Assembler Enhanced environment variables.

Link-Edited Modules

Table 856 summarizes changes to the link-edited modules shipped by IBM, which should go into a data set with attributes DCB=(RECFM=U,LRECL=80,BLKSIZE=1200). This information is presented in alphabetic order by the name of the link-edited module.

Table 856. Changes to Link-Edited Modules for File System Tools

Link-Edited Module New, Changed, or No Longer Supported? Description of Change
CISO Changed Added support for new ZFILE commands.
COMX Changed Added support for new ZFILE commands.

Members (Object Files)

Table 857 summarizes changes to members (object files). This information is presented in alphabetic order by the name of the member (object file).

Notes:

  1. You must recompile or reassemble a member (object file) if it has changed.

  2. You must prelink and link a dynamic load module (DLM) if it has changed.

Table 857. Changes to Members (Object Files) for File System Tools

Member (Object File) DLM/DLL New, Changed, or No Longer Supported? Type Description of Change
CBOT CBOT Changed C Language Added additional default directories.
CFIM CFIM Changed C Language Moved a majority of ZFILE command processing to the CFIX DLM.
CFIND1 CFJF New C Language Created for the entry point of the ZFILE find command.
CFIND2 CFJF New C Language Created for processing of the ZFILE find command.
CFIND3 CFJF New C Language Created for the command routines of the ZFILE find command.
CFIND4 CFJF New C Language Created for format processing of the ZFILE find commad.
CFIND5 CFJF New C Language Created for miscellaneous functions of the ZFILE find command.
CFIND6 CFJF New C Language Created for operator processing of the ZFILE find command.
CFIND7 CFJF New C Language Created for option processing of the ZFILE find command.
CFIND8 CFJF New C Language Created for file mode processing of the ZFILE find command.
CFIND9 CFJF New C Language Created for file mode display of the ZFILE find command.
CFIP CFIP Changed C++ Language Updated for environment variables.
CFIR CFIR Changed C++ Language Updated for environment variables.
CFIS CFIS Changed C++ Language Updated for environment variables.
CFIV CFIV Changed C++ Language Updated for environment variables.
CFJE CFJE New C++ Language Created for the ZFILE export command.
CFJG CFJG New C Language Created for the ZFILE grep command.
CFJT CFJT New C Language Created for the ZFILE tr command.
CFJX CFJX New C Language Created for ZFILE xargs processing in the ZFILE xargs command.
CHEX01 CFJH New C Language Created for the ZFILE hex command entry point.
CHEX02 CFJH New C Language Created for ZFILE hex command data conversion.
CHEX03 CFJH New C Language Created for the ZFILE hex command display.
CHEX04 CFJH New C Language Created for ZFILE hex command input message processing.
CHEX05 CFJH New C Language Created for ZFILE hex command format processing.
CPS01 CFJP New C Language Created for the ZFILE ps command entry point.
CPS02 CFJP New C Language Created for ZFILE ps command field name processing.
CPS03 CFJP New C Language Created for the ZFILE ps command display.
CSED01 CFJS New C Language Created for the ZFILE sed command entry point.
CSED02 CFJS New C Language Created for command parsing of the ZFILE sed command command line.
CSED03 CFJS New C Language Created for miscellaneous processing of the ZFILE sed command.
CSED04 CFJS New C Language Created for ZFILE sed command input message processing.
CSH01 CFIX New C Language Created for the ZFILE parser entry point.
CSH02 CFIX New C Language Created for alias processing in the ZFILE parser.
CSH03 CFIX New C Language Created for arithmetic processing in the ZFILE parser.
CSH04 CFIX New C Language Created for arithmetic expression parsing in the ZFILE parser.
CSH05 CFIX New C Language Created for built-in command processing in the ZFILE parser.
CSH06 CFIX New C Language Created for error processing in the ZFILE parser.
CSH07 CFIX New C Language Created for top-level execution routines in the ZFILE parser.
CSH08 CFIX New C Language Created for running commands in the ZFILE parser.
CSH09 CFIX New C Language Created for argument evaluation in the ZFILE parser.
CSH10 CFIX New C Language Created for initialization of the ZFILE parser.
CSH11 CFIX New C Language Created for input routines in the ZFILE parser.
CSH12 CFIX New C Language Created for job control in the ZFILE parser.
CSH13 CFIX New C Language Created for memory functions in the ZFILE parser.
CSH14 CFIX New C Language Created for running miscellaneous built-in ZFILE parser commands.
CSH15 CFIX New C Language Created for string functions in the ZFILE parser.
CSH16 CFIX New C Language Created for parsed ZFILE parser command routines.
CSH17 CFIX New C Language Created for option processing in the ZFILE parser.
CSH18 CFIX New C Language Created for output routines in the ZFILE parser.
CSH19 CFIX New C Language Created for parser code in the ZFILE parser.
CSH20 CFIX New C Language Created for redirection in the ZFILE parser.
CSH21 CFIX New C Language Created for ZFILE parser diagnostics.
CSH22 CFIX New C Language Created for syntax tables in the ZFILE parser.
CSH24 CFIX New C Language Created for signal handling in the ZFILE parser.
CSH25 CFIX New C Language Created for variable table routines in the ZFILE parser.
CTR001 CFJA New C Language Created for the ZFILE tr command.
CTR002 CFJA New C Language Created for the ZFILE tr command.
I$DIR CFIP, CFIR, CFIS, CFIV Changed C++ Language Updated for environment variables.
I$ENV CFIR, CFIS, CFJE Changed C++ Language Updated for environment variables.
I$FILE CFIR, CFIS, CFJE Changed C++ Language Updated for environment variables.
I$MSG CFIP, CFIR, CFIV No Longer Supported C++ Language Removed and replaced by CGETOP40.

Object Code Only (OCO) Stubs

There are no changes.

Configuration Constant (CONKC) Tags

There are no changes.

Control Program Interface (CINFC) Tags

There are no changes.

Copy Members

Table 858 summarizes the copy member changes. This information is presented in alphabetic order by the name of the copy member.

Table 858. Changes to Copy Members for File System Tools

Copy Member Type CSECT Where Copy Member Is Located DLM Where CSECT Is Located New, Changed, or No Longer Supported? Description of Change
CCE4 Control Program CCIISC Not Applicable Changed Updated to handle tpf_fork changes.

Fixed File Records

There are no changes.

Macros

The following section summarizes the macro changes. This information is presented in alphabetic order by the type of macro.

Advanced Program-to-Program Communications (APPC) Macros

There are no changes.

Communication Macros and Statements

There are no changes.

Data Macros

Table 859 summarizes the data macro changes. This information is presented in alphabetic order by the name of the data macro.

Table 859. Changes to Data Macros for File System Tools

Data Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs Using This Data Macro?
IDARGV New No
IDENV Changed Yes
IPROC Changed No

General Macros

There are no changes.

Selected Equate Macros

There are no changes.

Structured Programming Macros (SPMs)

There are no changes.

System Initialization Program (SIP) Skeleton and Internal Macros (Inner Macros)

Table 860 summarizes the system initialization program (SIP) skeleton and internal macro changes. This information is presented in alphabetic order by the name of the SIP skeleton and internal macro. If the SIP skeleton and internal macro (inner macro) is changed, you must reassemble the SIP Stage I deck and run the appropriate job control language (JCL) jobs from the SIP Stage II deck.

Table 860. Changes to SIP Skeleton and Internal Macros for File System Tools

SIP Skeleton and Internal Macro New, Changed, or No Longer Supported?
SPPGML Changed

System Initialization Program (SIP) Stage I Macros and Statements

There are no changes.

System Initialization Program (SIP) Stage II Macros

Table 861 summarizes system initialization program (SIP) Stage II macro changes. This information is presented in alphabetic order by the name of the SIP Stage II macro. If IBMPAL is changed, you must run the system allocator (SALO) and load the new program allocation table (PAT) to the TPF 4.1 system.

Table 861. Changes to SIP Stage II Macros for File System Tools

SIP Stage II Macro New, Changed, or No Longer Supported?
IBMPAL Changed

System Communication Keypoint (SCK) Generation Macros

There are no changes.

System Macros

Table 862 summarizes system macro changes. This information is presented in alphabetic order by the name of the system macro. See TPF System Macros for a complete description of all system macros.

Table 862. Changes to System Macros for File System Tools

System Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
IBMSVC Changed Yes

System Macros (IBM Use Only)

Table 863 summarizes system macro changes that are for IBM use only. This information is presented in alphabetic order by the name of the system macro.

Table 863. Changes to System Macros (IBM Use Only) for File System Tools

System Macro (IBM Use Only) New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
$FORKC Changed Yes

Segments

Table 864 summarizes segment changes. This information is presented in alphabetic order by the name of the segment.

Table 864. Changes to Segments for File System Tools

Segment Type Link-Edit Module (Where Offline Segment Is Linked) New, Changed, or No Longer Supported? Description of Change
CCIISC CSECT Not Applicable Not Applicable No changes were made but it must be reassembled because of updates to the tpf_fork function.
CCNUCL CSECT Not Applicable Not Applicable No changes were made but it must be reassembled because of updates to the tpf_fork function.
CCMCDC CSECT Not Applicable Not Applicable No changes were made but it must be reassembled because of updates to the tpf_fork function.
CFIQ C Language CFIQ Not Applicable No changes were made but it must be recompiled because of updates to the tpf_fork function.
CFTP3 C Language CFTP Not Applicable No changes were made but it must be recompiled because of updates to the tpf_fork function.
CINET3 C Language CLTW Not Applicable No changes were made but it must be recompiled because of updates to the tpf_fork function.
CINET4 C Language CLTX Not Applicable No changes were made but it must be recompiled because of updates to the tpf_fork function.
CINET7 C Language CLTZ Not Applicable No changes were made but it must be recompiled because of updates to the tpf_fork function.
CTKS Real-Time Assembler Not Applicable Not Applicable No changes were made but it must be reassembled because of updates to the tpf_fork function.

System Equates

There are no changes.

User Exits

There are no changes.

Functional and Operational Changes

The following section summarizes functional and operational changes. This information is presented in alphabetic order by the functional or operational change.

See Appendix A, "PUT 2-15 Interface Changes by Authorized Program Analysis Report (APAR)" for a summary of functional and operational changes by APAR.

Commands

Table 865 summarizes command changes. This information is presented in alphabetic order by the name of the command. See TPF Operations for a complete description of all commands.

Attention: Changes to commands can impact any automation programs you are using in your complex.

Table 865. Changes to Commands for File System Tools

Command New, Changed, or No Longer Supported? Description of Change
ZFILE New Created to activate a TPF segment or script.
ZFILE cat Changed Updated to reflect pipe and quoting mechanisms.
ZFILE cd Changed Updated to reflect quoting mechanisms.
ZFILE chmod Changed Updated to reflect quoting mechanisms.
ZFILE chown Changed Updated to reflect quoting mechanisms.
ZFILE cp Changed Updated to reflect quoting mechanisms.
ZFILE dd Changed Updated to reflect quoting mechanisms.
ZFILE echo Changed Updated to reflect pipe and quoting mechanisms; updated the example.
ZFILE export New Created to create and display ZFILE environment variables.
ZFILE find New Created to find files.
ZFILE grep New Created to search a file for a specified pattern.
ZFILE head Changed Updated to reflect pipe and quoting mechanisms.
ZFILE hex New Created to display the contents of a file.
ZFILE kill Changed Updated to reflect quoting mechanisms.
ZFILE ln Changed Updated to reflect quoting mechanisms.
ZFILE ls Changed Updated to reflect pipe and quoting mechanisms.
ZFILE mkdir Changed Updated to reflect quoting mechanisms.
ZFILE mknod Changed Updated to reflect quoting mechanisms.
ZFILE mv Changed Updated to reflect quoting mechanisms.
ZFILE ps New Created to display process information.
ZFILE pwd Changed Updated to reflect quoting mechanisms.
ZFILE rm Changed Updated to reflect quoting mechanisms.
ZFILE rmdir Changed Updated to reflect quoting mechanisms.
ZFILE sed New Created to edit files in a noninteractive stream.
ZFILE tail Changed Updated to reflect pipe and quoting mechanisms.
ZFILE tee New Created to duplicate the output stream.
ZFILE touch Changed Updated to reflect quoting mechanisms.
ZFILE tr New Created to translate or delete characters.
ZFILE unset New Created to unset the values of ZFILE environment variables.
ZFILE xargs New Created to construct an argument list and run a command.

Messages and System Errors

There are no changes.

Performance or Tuning Changes

There are no changes.

Storage Considerations and Changes

There are no changes.

System Initialization Program (SIP) and System Generation Changes

There are no changes.

Loading Process Changes

There are no changes.

Online System Load Changes

There are no changes.

Publication Changes

Table 866 summarizes changes to the publications in the TPF library. This information is presented in alphabetic order by the publication title. See the TPF Library Guide for more information about the TPF library.

Table 866. Changes to TPF Publications for File System Tools

Publication Title Softcopy File Name Description of Change
TPF Application Programming GTPAPP0C Updated to reflect appropriate use of the vertical bar (|) as a pipe.
TPF C/C++ Language Support User's Guide GTPCLU0D Updated with new tpf_fork information.
TPF Library Guide GTPDOC0D Updated with definitions for new terminology in the master glossary.
TPF Migration Guide: Program Update Tapes GTPMG203 Updated with migration considerations for file system tools.
TPF Operations GTPOPR0D Updated with information about the commands that were added and changed for file system tools.
TPF System Macros GTPSYS0D Updated with new parameters in the $FORKC macro.

Host System Changes

There are no changes.

Application Programming Interface (API) Changes

The tpf_fork function has been enhanced to allow you to specify how you want to pass a string of data. See the TPF C/C++ Language Support User's Guide for more specific information about tpf_fork enhancements.

Database Changes

There are no changes.

Feature Changes

There are no changes.

Installation Validation

There are no changes.

Migration Scenarios

To add file system tools to your existing TPF 4.1 system, do the following:

  1. Install program update tape (PUT) 13.
  2. Run the LIBI offline program for all changed library interface scripts listed in Table 854.
  3. Run the CBLD program for the build scripts listed in Table 855, Table 858, and Table 859.
  4. Verify that the following are installed:
  5. Reassemble or recompile the following:
  6. Link-edit the DLM/DLLs listed in Table 857 and Table 858.
  7. Load the updated object code to your TPF 4.1 system.
  8. Ensure that the TPF 4.1 system is in NORM state before running any application programs.