Programming Reference Manual - Public Support Login - Unisys

OS 2200 

Program-Callable FURPUR (PCFP) 

Programming Reference Manual 

ClearPath OS 2200 Release 11.3 

September 2008 7830 9796–013 

unisys 

imagine it. done.

NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THIS DOCUMENT. Any product or related information 

described herein is only furnished pursuant and subject to the terms and conditions of a duly executed agreement to 

purchase or lease equipment or to license software. The only warranties made by Unisys, if any, with respect to the 

products described in this document are set forth in such agreement. Unisys cannot accept any financial or other 

responsibility that may be the result of your use of the information in this document or software material, including 

direct, special, or consequential damages. 

You should be very careful to ensure that the use of this information and/or software material complies with the laws, 

rules, and regulations of the jurisdictions with respect to which it is used. 

The information contained herein is subject to change without notice. Revisions may be issued to advise of such 

changes and/or additions. 

Notice to U.S. Government End Users: This is commercial computer software or hardware documentation developed at 

private expense. Use, reproduction, or disclosure by the Government is subject to the terms of Unisys standard 

commercial license for the products, and where applicable, the restricted/limited rights provisions of the contract data 

rights clauses. 

Unisys and ClearPath are registered trademarks of Unisys Corporation in the United States and other countries. 

All other brands and products referenced in this document are acknowledged to be the trademarks or registered 

trademarks of their respective holders.

OS 2200 

Program-Callable FURPUR 

(PCFP) 

Programming Reference 

Manual 

ClearPath OS 2200 

Release 11.3 

OS 2200 

Program-Callable 

FURPUR (PCFP) 

Programming 

Reference 

Manual 

ClearPath OS 

2200 Release 

11.3 

7830 9796–013 7830 9796–013 

Bend here, peel upwards and apply to spine.

Contents 

Section 1. Using PCFP 

1.1. Definition of PCFP .................................................................... 1–1 

1.2. File Types Operated on by PCFP ............................................. 1–2 

1.3. Calling PCFP Functions ............................................................ 1–3 

1.3.1. Calling PCFP to Delete a File ........................................... 1–3 

1.3.2. Calling PCFP to Copy a File ............................................. 1–9 

1.3.3. Calling PCFP to Acquire Element Information 

from a Program File .................................................. 1–14 

1.4. Summary of PCFP Functions ................................................. 1–21 

1.5. PCFP Processor ..................................................................... 1–23 

Section 2. Functions of PCFP 

2.1. Typical Form of PCFP Functions .............................................. 2–1 

2.2. Data Types ............................................................................... 2–3 

2.3. File Identifiers .......................................................................... 2–4 

2.4. Function Packet ....................................................................... 2–8 

2.4.1. Generic Part of the Function Packet ............................... 2–8 

2.4.2. Return-Information Part of the Function Packet ........... 2–13 

2.5. Work Area .............................................................................. 2–14 

2.6. Wild-Card Characters ............................................................. 2–15 

2.7. Function-Specific Interface Information ................................. 2–16 

2.8. Multi-Activity Programs .......................................................... 2–17 

Section 3. Acquiring General File Information 

3.1. Acquire File Information (ACQ_FILE_INFO) ............................. 3–1 

3.1.1. Parameters ...................................................................... 3–1 

3.1.2. Function Packet ............................................................... 3–1 

3.1.3. File Identifier .................................................................... 3–3 

3.1.4. Return Information (C Language) .................................... 3–4 

3.1.4.1. Nonfloating Part ...................................................... 3–5 

3.1.4.2. Cataloged File Part ................................................ 3–11 

3.1.4.3. Mass Storage Part ................................................ 3–15 

3.1.4.4. Tape Part............................................................... 3–18 

3.1.4.5. Security Part ......................................................... 3–24 

3.1.4.6. Volume Part .......................................................... 3–25 

3.1.4.7. Run Assignment Part ............................................ 3–27 

3.1.5. Return Information (COBOL and FORTRAN) ................ 3–28 

3.1.5.1. Short Form Return Information (COBOL 

and FORTRAN) ................................................. 3–29 

7830 9796–013 iii

Contents 

3.1.5.2. Long Form Return Information (COBOL and 

FORTRAN) ........................................................ 3–30 

3.1.6. Work Area ...................................................................... 3–35 

3.2. Acquire File List (ACQ_FILE_LIST) ......................................... 3–36 

3.2.1. Parameters ..................................................................... 3–36 

3.2.2. Function Packet ............................................................. 3–37 

3.2.3. Return Information ......................................................... 3–46 

3.2.4. Work Area ...................................................................... 3–47 

Section 4. Changing File Attributes 

4.1. Change File Specific Attributes (CHG_FILE) ............................. 4–1 

4.1.1. Parameters ....................................................................... 4–2 



4.1.4. Work Area ........................................................................ 4–7 

4.2. Change File Cycle Attributes (CHG_FILE_CYC) ........................ 4–7 

4.2.1. Parameters ....................................................................... 4–8 



4.2.4. Work Area ........................................................................ 4–9 

4.3. Change File Security Attributes (CHG_FILE_SEC) .................. 4–10 

4.3.1. Parameters ..................................................................... 4–10 


4.3.3. File Identifier .................................................................. 4–12 

4.3.4. Work Area ...................................................................... 4–12 

4.4. Change File Keys (CHG_FILE_KEYS) ...................................... 4–13 

4.4.1. Parameters ..................................................................... 4–13 



4.4.4. Work Area ...................................................................... 4–14 

4.5. Change File Name (CHG_FILE_NAME) .................................. 4–15 

4.5.1. Parameters ..................................................................... 4–15 



4.5.4. Work Area ...................................................................... 4–17 

Section 5. Copying Between Files 

5.1. Copy RAF to RAF (COPY_RAF_RAF) ........................................ 5–1 

5.1.1. Parameters ....................................................................... 5–2 


5.1.3. Source File Identifier ........................................................ 5–3 

5.1.4. Destination File Identifier ................................................. 5–3 

5.1.5. Work Area ........................................................................ 5–3 

5.2. Copy RAF to SAF (COPY_RAF_SAF) ........................................ 5–4 

5.2.1. Parameters ....................................................................... 5–6 


5.2.3. Source File Identifier ...................................................... 5–10 

5.2.4. Destination File Identifier ............................................... 5–10 

5.2.5. User Descriptor Data ..................................................... 5–10 

iv 7830 9796–013

Contents 

5.2.6. Return Entry .................................................................. 5–11 

5.2.7. Work Area ..................................................................... 5–13 

5.3. Copy SAF to RAF (COPY_SAF_RAF) ..................................... 5–14 

5.3.1. Parameters .................................................................... 5–16 


5.3.3. Source File Identifier ..................................................... 5–20 

5.3.4. Destination File Identifier .............................................. 5–20 

5.3.5. Descriptor Return Area ................................................. 5–20 

5.3.6. Work Area ..................................................................... 5–23 

5.4. Copy SAF to SAF (COPY_SAF_SAF) ...................................... 5–24 

5.4.1. Parameters .................................................................... 5–26 


5.4.3. Source File Identifier ..................................................... 5–32 

5.4.4. Destination File Identifier .............................................. 5–32 

5.4.5. User Descriptor Data ..................................................... 5–32 

5.4.6. Return Entry .................................................................. 5–32 

5.4.7. Descriptor Return Area ................................................. 5–33 

5.4.8. Work Area ..................................................................... 5–33 

Section 6. Acquiring Program File Information 

6.1. Acquire Basic Program File Information 

(ACQ_BASIC_PF_INFO) ....................................................... 6–1 

6.1.1. Parameters ...................................................................... 6–2 



6.1.4. Work Area ..................................................................... 6–10 

6.2. Acquire Element Information (ACQ_ELT_INFO) .................... 6–11 

6.2.1. Parameters .................................................................... 6–11 



6.2.4. Return Entry .................................................................. 6–17 

6.2.5. Work Area ..................................................................... 6–23 

6.3. Acquire Relocatable Entry Point Information 

(ACQ_REL_EP_INFO) ........................................................ 6–24 

6.3.1. Parameters .................................................................... 6–24 



6.3.4. Return Entry .................................................................. 6–27 

6.3.5. Work Area ..................................................................... 6–28 

6.4. Acquire Object Module Entry Point Information 

(ACQ_OM_EP_INFO) ......................................................... 6–29 

6.4.1. Parameters .................................................................... 6–30 



6.4.4. Return Entry .................................................................. 6–35 

6.4.5. Work Area ..................................................................... 6–38 

6.5. Acquire Procedure Information (ACQ_PROC_INFO) ............. 6–39 

6.5.1. Parameters .................................................................... 6–39 



7830 9796–013 v

Contents 

6.5.4. Return Entry for MASM, FORTRAN, and PLUS 

Procedures ................................................................. 6–42 

6.5.5. Return Entry for COBOL Procedures ............................. 6–44 

6.5.6. Work Area ...................................................................... 6–46 

Section 7. Copying Program File Elements 

7.1. Copy Elements (COPY_ELT) ..................................................... 7–1 

7.1.1. Parameters ....................................................................... 7–2 




7.1.5. Return Entry ................................................................... 7–10 

7.1.6. Work Area ...................................................................... 7–13 

7.2. Copy Symbolic Element to RAF 

(COPY_SYM_ELT_RAF)...................................................... 7–14 

7.2.1. Parameters ..................................................................... 7–14 




7.2.5. Work Area ...................................................................... 7–17 

7.3. Copy RAF to Symbolic Element 

(COPY_RAF_SYM_ELT)...................................................... 7–17 

7.3.1. Parameters ..................................................................... 7–17 




7.3.5. Work Area ...................................................................... 7–20 

7.4. Copy Omnibus Element to RAF 

(COPY_OMN_ELT_RAF)..................................................... 7–21 

7.4.1. Parameters ..................................................................... 7–21 




7.4.5. Work Area ...................................................................... 7–23 

7.5. Copy RAF to Omnibus Element 

(COPY_RAF_OMN_ELT)..................................................... 7–23 

7.5.1. Parameters ..................................................................... 7–23 




7.5.5. Work Area ...................................................................... 7–26 

Section 8. Updating Program Files 

8.1. Change Element Attributes (CHG_ELT) ................................... 8–1 

8.1.1. Parameters ....................................................................... 8–2 



8.1.4. Return Entry ..................................................................... 8–9 

8.1.5. Work Area ...................................................................... 8–10 

vi 7830 9796–013

Contents 

8.2. Delete Elements (DELETE_ELT) ............................................ 8–10 

8.2.1. Parameters .................................................................... 8–11 



8.2.4. Return Entry .................................................................. 8–14 

8.2.5. Work Area ..................................................................... 8–14 

8.3. Undelete Elements (UNDELETE_ELT) ................................... 8–15 

8.3.1. Parameters .................................................................... 8–16 



8.3.4. Return Entry .................................................................. 8–22 

8.3.5. Work Area ..................................................................... 8–23 

8.4. Pack Program File (PACK_PF) ................................................ 8–24 

8.4.1. Parameters .................................................................... 8–25 



8.4.4. Work Area ..................................................................... 8–31 

8.4.4.1. Standard Method Work Area Requirements ........ 8–31 

8.4.4.2. Copy Method Work Area Requirements .............. 8–33 

8.5. Create Program File Entry Point Table (PREP_PF) ................. 8–36 

8.5.1. Parameters .................................................................... 8–36 



8.5.4. Work Area ..................................................................... 8–39 

Section 9. Erasing and Deleting Files 

9.1. Erase RAF (ERASE_RAF) ......................................................... 9–1 

9.1.1. Parameters ...................................................................... 9–2 



9.1.4. Work Area ....................................................................... 9–4 

9.2. Delete File (DELETE_FILE)....................................................... 9–4 

9.2.1. Parameters ...................................................................... 9–4 



9.2.4. Work Area ....................................................................... 9–5 

Section 10. Positioning and Closing Tape Files 

10.1. Move SAF (MOVE_SAF) ........................................................ 10–1 

10.1.1. Parameters .................................................................... 10–2 


10.1.3. Actions Performed by the MOVE_SAF Function .......... 10–9 

10.1.4. File Identifier ................................................................ 10–10 

10.1.5. Work Area ................................................................... 10–10 

10.1.6. Fast Tape Access Considerations ............................... 10–10 

10.2. Close SAF (CLOSE_SAF) ..................................................... 10–12 

10.2.1. Parameters .................................................................. 10–13 

10.2.2. Function Packet ........................................................... 10–13 

7830 9796–013 vii

Contents 

10.2.3. File Identifier ................................................................ 10–14 

10.2.4. Work Area .................................................................... 10–14 

Section 11. Using PCFP with C 

11.1. Include Considerations ........................................................... 11–1 

11.2. Naming Conventions .............................................................. 11–2 

11.2.1. Function Names ............................................................. 11–3 

11.2.2. Typedef Names .............................................................. 11–3 

11.2.3. Item Names ................................................................... 11–3 

11.2.4. Names of Constants ...................................................... 11–3 

11.3. PCFP Data Types .................................................................... 11–4 

11.3.1. Structure Declarations ................................................... 11–5 

11.3.2. Implementing Generic Data Types ................................ 11–5 

11.4. Operating Rules and Coding Sequences ................................ 11–6 

11.4.1. Parameter Definitions .................................................... 11–6 

11.4.2. Initializing Input Parameters ........................................... 11–7 

11.4.3. Assigning Values to Character Strings Within 

Structures .................................................................. 11–7 

11.4.4. Work Area Parameter .................................................... 11–8 

11.4.5. Calling PCFP ................................................................... 11–8 

11.4.6. Handling Error Conditions .............................................. 11–9 

11.4.7. Items in a Bit Array ........................................................ 11–9 

11.4.8. Date-Time Items .......................................................... 11–10 

11.4.9. Return Area .................................................................. 11–10 

11.4.9.1. General Considerations ....................................... 11–10 

11.4.9.2. Special Considerations for _fp_acq_file_info 

and _fp_acq_file_list ........................................ 11–13 

11.5. Compiling and Linking Programs That Use PCFP ................. 11–14 

11.6. Programming Examples ....................................................... 11–14 

11.6.1. Calling PCFP to Delete a File ....................................... 11–15 

11.6.2. Calling PCFP to Copy a File .......................................... 11–16 


from a Program File ................................................. 11–17 

Section 12. Using PCFP with COBOL 

12.1. Copy Considerations ............................................................... 12–1 


12.2.1. Subroutine Names ......................................................... 12–3 

12.2.2. Item Names ................................................................... 12–3 

12.2.3. Names of Constants ...................................................... 12–4 

12.3. PCFP Data Types .................................................................... 12–4 

12.3.1. Record Definitions ......................................................... 12–5 

12.3.2. Implementing Generic Data Types ................................ 12–5 

12.4. Operating Rules and Coding Sequences ................................ 12–6 

12.4.1. Initializing Input Parameters ........................................... 12–6 

12.4.2. Work Area Specification ................................................. 12–6 

12.4.3. Setting Items in a Bit Array ............................................ 12–7 

12.4.4. Handling Date-Time Items ............................................. 12–7 

12.4.5. Handling Error Conditions .............................................. 12–8 

viii 7830 9796–013

Contents 

12.4.6. Handling the Return Area Parameter ............................ 12–8 

12.5. Compiling and Linking Programs That Use PCFP .................. 12–9 

12.6. Programming Examples ......................................................... 12–9 


12.6.2. Calling PCFP to Copy a File ......................................... 12–11 


from a Program File ................................................ 12–14 

Section 13. Using PCFP with FORTRAN 

13.1. INCLUDE Element/Procedure Considerations ....................... 13–1 


13.2.1. Function Names ............................................................ 13–3 

13.2.2. Packet Names ............................................................... 13–4 

13.2.3. Item Names Within Packets ......................................... 13–4 

13.2.4. Names of Constants...................................................... 13–4 

13.3. Form of Packet Definitions .................................................... 13–4 

13.4. Operating Rules and Coding Sequences ............................... 13–6 

13.4.1. Specifying Items Within Packets .................................. 13–6 

13.4.2. Handling Repeating Return Information ........................ 13–6 

13.4.3. Specifying Work Area .................................................... 13–7 

13.4.4. Initializing Input Parameters .......................................... 13–7 

13.4.5. Handling Date-Time Items ............................................ 13–8 

13.4.6. Calling PCFP .................................................................. 13–8 

13.4.7. Handling Error Conditions ............................................. 13–9 

13.5. Compiling and Linking Programs That Use PCFP .................. 13–9 

13.6. Programming Examples ......................................................... 13–9 


13.6.2. Calling PCFP to Copy a File ......................................... 13–11 


from a Program File ................................................ 13–12 

Appendix A. Error Messages 

A.1. Warnings and Informational Messages ................................... A–2 

A.2. Errors ........................................................................................ A–4 

A.2.1. Calling Program Errors .................................................... A–5 

A.2.2. Execution I/O Errors ...................................................... A–21 

A.2.3. Execution Errors Other than I/O Errors—All File 

Types......................................................................... A–23 

A.2.4. Execution Errors Other than I/O Errors— 

Sequential-Access Files ............................................ A–29 


Random-Access Files................................................ A–33 

A.2.6. Execution Errors Other than I/O Errors—Program 

Files ........................................................................... A–37 

A.2.7. Errors Associated with Assigning and Freeing 

Files ........................................................................... A–42 

A.2.8. Errors Associated with the PACK_PF Function ............. A–45 

7830 9796–013 ix

Contents 

Appendix B. Summary of FURPUR Commands 

Appendix C. PACK_PF Operation and Performance 

C.1. Standard Method Performance ............................................... C–1 

C.2. Copy Method Performance ..................................................... C–4 

C.3. Performance Comparison ........................................................ C–6 

C.4. File Contents in Error Cases .................................................... C–7 

Glossary ............................................................................................. 1 

Index ............................................................................................. 1 

x 7830 9796–013

Figures 

1–1. Calling the DELETE_FILE Function .................................................................... 1–4 

1–2. DELETE_FILE Function Packet Items ................................................................ 1–5 

1–3. DELETE_FILE Function Packet with Numeric Equivalents ................................ 1–6 

1–4. File Identifier Packet Items ................................................................................ 1–7 

1–5. File Identifier Packet Items with Numeric Equivalents ...................................... 1–8 

1–6. Calling the COPY_RAF_RAF Function................................................................ 1–9 

1–7. COPY_RAF_RAF Function Packet Items ......................................................... 1–10 

1–8. COPY_RAF_RAF Function Packet with Numeric Equivalents ......................... 1–11 

1–9. Source File Identifier Packet Items .................................................................. 1–12 

1–10. Source File Identifier Packet Items with Numeric Equivalents ........................ 1–12 

1–11. Calling the ACQ_ELT_INFO Function .............................................................. 1–14 

1–12. ACQ_ELT_INFO Function Packet Items (cont.) ............................................... 1–16 

1–12. ACQ_ELT_INFO Function Packet Items .......................................................... 1–17 

1–13. ACQ_ELT_INFO Function Packet Items with Numeric Equivalents 

(cont.) ........................................................................................................... 1–18 

1–13. ACQ_ELT_INFO Function Packet Items with Numeric Equivalents ................ 1–19 

2–1. File Identifier Packet Items ................................................................................ 2–5 

2–2. Generic Part of the Function Packet .................................................................. 2–9 

2–3. Return-Information Part of the Function Packet .............................................. 2–13 

3–1. ACQ_FILE_INFO Function Packet Items ........................................................... 3–2 

3–2. Nonfloating Part of the Return Entry for C Language ........................................ 3–5 

3–3. Cataloged File Part of the Return Entry for C Language .................................. 3–11 

3–4. Mass Storage Part of the Return Entry for C Language .................................. 3–15 

3–5. Tape Part of the Return Entry for C Language ................................................. 3–19 

3–6. Security Part of Return Entry for C Language .................................................. 3–24 

3–7. Volume Part of the Return Entry for C Language ............................................ 3–26 

3–8. Run Assignment Part of the Return Entry for C Language .............................. 3–27 

3–9. Mass Storage Part of the Return Entry for COBOL and FORTRAN 

Short Form ................................................................................................... 3–29 

3–10. Long Form Return Entry for Mass Storage File for COBOL and 

FORTRAN (cont.) ......................................................................................... 3–30 

3-10. Long Form Return Entry for Mass Storage File for COBOL and 

FORTRAN (cont.) ......................................................................................... 3–31 

3–10. Long Form Return Entry for Mass Storage File for COBOL and 

FORTRAN .................................................................................................... 3–32 

3–11. Long Form Tape Part of the Return Entry for COBOL and FORTRAN ............ 3–33 

3–12. ACQ_FILE_LIST Function Packet Items (cont.) ............................................... 3–37 

3–12. ACQ_FILE_LIST Function Packet Items .......................................................... 3–38 

4–1. CHG_FILE Function Packet Items ...................................................................... 4–2 

7830 9796–013 xi

Figures 

4–2. CHG_FILE_CYC Function Packet Items ............................................................. 4–8 

4–3. CHG_FILE_SEC Function Packet Items ............................................................ 4–11 

4–4. CHG_FILE_KEYS Function Packet Items .......................................................... 4–13 

4–5. CHG_FILE_NAME Function Packet Items ........................................................ 4–16 

5–1. COPY_RAF_RAF Function Packet Items ............................................................ 5–2 

5–2. COPY_RAF_SAF Function Packet Items ............................................................ 5–7 

5–3. COPY_RAF_SAF and COPY_SAF_SAF Return Entry Items ............................. 5–12 

5–4. COPY_SAF_RAF Function Packet Items .......................................................... 5–16 

5–5. Descriptor Return Area for COPY_SAF_RAF and COPY_SAF_SAF ................. 5–21 

5–6. COPY_SAF_SAF Function Packet and Return Area Items ............................... 5–27 

6–1. ACQ_BASIC_PF_INFO Function Packet Items ................................................... 6–3 

6–2. ACQ_ELT_INFO Function Packet Items ........................................................... 6–12 

6–3. The First 14 Words of the Return Entry ........................................................... 6–17 

6–4. ACQ_REL_EP_INFO Function Packet Items .................................................... 6–25 

6–5. ACQ_REL_EP_INFO Return Entry Items .......................................................... 6–27 

6–6. ACQ_OM_EP_INFO Function Packet Items ..................................................... 6–31 

6–7. ACQ_OM_EP_INFO Return Entry Items .......................................................... 6–35 

6–8. ACQ_PROC_INFO Function Packet Items ....................................................... 6–40 

6–9. ACQ_PROC_INFO Return Entry Structure When 

PROC_TABLE = MASM_PROC or FTN_PLS_PROC.................................... 6–43 

6–10. ACQ_PROC_INFO Return Information Structure When 

PROC_TABLE = COBOL PROC ................................................................... 6–45 

7–1. COPY_ELT Function Packet Items ..................................................................... 7–3 

7–2. Summary Return Entry ..................................................................................... 7–11 

7–3. COPY_SYM_ELT_RAF Function Packet Items ................................................. 7–15 

7–4. COPY_RAF_SYM_ELT Function Packet Items ................................................. 7–18 

7–5. COPY_OMN_ELT_RAF Function Packet Items ................................................ 7–21 

7–6. COPY_RAF_OMN_ELT Function Packet Items ................................................ 7–24 

8–1. CHG_ELT Function Packet Items ....................................................................... 8–3 

8–2. DELETE_ELT Function Packet Items ................................................................ 8–11 

8–3. UNDELETE_ELT Function Packet Items .......................................................... 8–17 

8–4. PACK_PF Function Packet Items ...................................................................... 8–26 

8–5. PREP_PF Function Packet Items ...................................................................... 8–37 

9–1. ERASE_RAF Function Packet Items ................................................................... 9–2 

9–2. DELETE_FILE Function Packet Items ................................................................. 9–5 

10–1. MOVE_SAF Function Packet Items .................................................................. 10–3 

10–2. CLOSE_SAF Function Packet Items ............................................................... 10–13 

xii 7830 9796–013

Tables 

1–1. Summary of PCFP Functions ........................................................................... 1–21 

8–1. Absolute and Relative Sequence Numbers (sample)....................................... 8–15 

10–1. Actions Performed by MOVE_SAF Function ................................................... 10–9 

B–1. Summary of FURPUR Commands ..................................................................... B–2 

C–1. Standard Method Performance Comparison ..................................................... C–3 

C–2. Copy Method Performance Comparison ........................................................... C–5 

7830 9796–013 xiii

Tables 

xiv 7830 9796–013

Section 1 

Using PCFP 

This manual is written to provide a general understanding of how to use PCFP and to 

serve as a specific reference for information on each of the PCFP functions. 

Documentation Updates 

This document contains all the information that was available at the time of publication. 

Changes identified after release of this document are included in problem list entry (PLE) 

18564441. To obtain a copy of the PLE, contact your Unisys service representative or 

access the current PLE from the Unisys Product Support Web site: 

http://www.support.unisys.com/all/ple/18564441 

Note: If you are not logged into the Product Support site, you will be asked to do so. 

The primary audience for this document is the programmer who has experience on the 

OS 2200 system and knows at least one of the programming languages from which you 

can call PCFP. 

This section explains how to use Program-Callable FURPUR (PCFP) and provides 

examples. These examples are intended to help you understand how PCFP works in 

general. They do not cover every application of PCFP. The examples show you 

• How to prepare a function packet before calling a function 

• How to handle return information 

After reading this section, you should have a general understanding of how to use PCFP 

within programs. Sections 2 – 10 contain detailed information on each PCFP function. 

Sections 11 – 13 contain detailed information on each language from which PCFP can be 

used. 

1.1. Definition of PCFP 

Designed to run on the OS 1100 and 2200 Extended Mode systems, Program-Callable 

FURPUR (PCFP) extends the capabilities of the FURPUR processor, making its 

capabilities available for applications written in C, FORTRAN, and COBOL. Providing a 

set of FURPUR-like functions, PCFP is a utility that provides you with a straightforward 

way to have programs perform the file and element handling capabilities of FURPUR 

without interrupting the flow of the program. PCFP allows you to make file handling 

decisions, include those decisions in your program by specifying packet parameters for a 

particular PCFP function, and call the function to operate on files you specify. Results 

7830 9796–013 1–1

Using PCFP 

are returned to your program either through the function packet or in a data structure you 

provide. 

You can call PCFP any number of times from within a program. Each call performs a 

PCFP operation on a single file or element, unless a function allows for a list of multiple 

files or elements. With some considerations and restrictions, you can also call PCFP 

simultaneously from multiple activities running in the same program. See 2.8 for 

additional information on multi-activity programs. 

Perform the following five steps to use PCFP: 

1. Include the appropriate data definition elements in your C, COBOL, or FORTRAN 

program. These data definition elements are part of the PCFP product release. 

2. Initialize the parameter packets. 

3. Set values to indicate the precise operation you want to perform. 

4. Call PCFP to perform the operation. 

5. Check the returned status for successful completion. 

No explicit linking is required to use PCFP in the extended-mode programming 

environment. 

1.2. File Types Operated on by PCFP 

Like FURPUR commands, PCFP functions operate on two types of files: 

• Random-access files (RAF), also referred to as mass storage files 

• Sequential-access files (SAF), also referred to as tape files 

A number of PCFP functions operate on a special type of RAF called a program file. 

There are two basic program file formats. The standard program file, referred to as a PF, 

has small variable-length tables. The large program, referred to as an LPF, has large 

fixed-length tables. For example, the PF has a normal maximum of 2,671 element table 

entries and can be expanded to 5,000 entries, while the LPF has a fixed maximum of 

26,146 element table entries. 

PF and LPF elements are limited to a maximum of 262,143 sectors of text for each 

element. A new program file type, the large element program, referred to as an LEPF, 

removes this limitation and allows elements to have over 262,143 sectors of text, if 

desired. An LEPF can be initialized with the small variable-length format of a standard 

program file (standard LEPF) or with the large fixed-length format of a large program file 

(large LEPF). 

All PCFP functions can operate on a PF, LPF, standard LEPF, or large LEPF. 

1–2 7830 9796–013

1.3. Calling PCFP Functions 

Using PCFP 

Figures 1–1, 1–6, and 1–11 show calls to three different PCFP functions. These figures 

illustrate PCFP functions of various complexities and with different mixes of input and 

output parameters. 

These figures contain logic charts depicting programs that set up parameters, call a 

PCFP function, and process the information returned by that PCFP function. The figures 

also contain supporting information, such as illustrations of the input parameters prior to 

calling the PCFP function and an illustration of a repeating return entry from a PCFP 

function that returns repeating information. 

In later sections of this manual, the information in these figures is shown in specific 

program language examples. Section 11 shows examples of these programs written in 

the C language. Section 12 shows examples of these programs written in COBOL. 

Section 13 shows examples of these programs written in FORTRAN. 

1.3.1. Calling PCFP to Delete a File 

Figure 1–1 shows the process associated with calling a PCFP function that requires 

minimal setup. In this figure, PCFP is called to delete the file A*B. Procedures 1 – 7 are 

explained following the figure. 

7830 9796–013 1–3

Using PCFP 

Figure 1–1. Calling the DELETE_FILE Function 

1–4 7830 9796–013

Procedure 1 

Using PCFP 

Clear the function packet to zeros to ensure that each item in the function packet is 

initially set at its default value. This allows you to concentrate on the values you want to 

change. 

Procedure 2 

Set the necessary items in the DELETE_FILE function packet: 

• Set INTERFACE_LEVEL to fp_interface_level_1 (which is defined as 1). 

• Set WORK_AREA_SIZE to fp_max_work_area_delete_file (1,000, which is the 

maximum work area size for the DELETE_FILE function). 

You do not need to set the other items in the function packet, either because the default 

value (0) is the desired value for these, or because PCFP uses these items to return 

information to the calling program. For example, in Figures 1–2 and 1–3, the items 

EXCLUSIVE_ASSIGN (a) and ZERO_RELEASED_STORAGE (b) in the specific part of the 

function packet are left initialized to FALSE (0). 

Figures 1–2 and 1–3 compare the items of the DELETE_FILE function packet to the 

function packet completed with the numeric equivalents for the items. 

0 INTERFACE_LEVEL 

1 a b 

2 WORK_AREA_SIZE 

3 SOFTWARE_LEVEL 

4 

5 GEN_DATE_TIME 

6 

7 ERROR_CLASS ERROR_FILE SUB_ERROR_CODE 

8 ERROR_CODE 

9 AUX_ERROR_CODE 

10 a b 

Figure 1–2. DELETE_FILE Function Packet Items 

7830 9796–013 1–5

Using PCFP 

0 1 0 

1 F F 0 

2 1000 

3 0 

4 

5 0 

6 

7 0 0 0 

8 0 

9 0 

10 F F 0 

Figure 1–3. DELETE_FILE Function Packet with Numeric Equivalents 

Procedure 3 

Clear the file identifier packet to zeros to ensure that each item in the packet is initially 

set at its default value. This allows you to concentrate on the values you want to 

change. 

Procedure 4 

Set the necessary items in the file identifier packet: 

• Set INTERFACE_LEVEL to fp_interface_level_1. 

• Set the QUALIFIER to A. 

• Set the FILENAME to B. 

You do not need to set the other items in the function packet, because the default value 

(0) is the desired value for these. 

Because DIRECTORY_ID is not set, PCFP uses the default directory-id for your run. 

Since F_CYCLE_TYPE and F_CYCLE are not set, PCFP uses the latest cycle for the file 

(relative cycle-0). Since READ_KEY and WRITE_KEY are not set, PCFP assumes the file 

has no read key and no write key. 

Figures 1–4 and 1–5 compare the items of the file identifier packet to the packet 

completed with the numeric and character equivalents for the items. 

1–6 7830 9796–013

0 


2 DIRECTORY_ID 


4 

5 QUALIFIER 

6 

7 

8 FILENAME 

9 

10 F_CYCLE_TYPE F_CYCLE 

11 READ_KEY 

12 READ_KEY 

13 WRITE_KEY 

14 WRITE_KEY 

Figure 1–4. File Identifier Packet Items 

Using PCFP 

7830 9796–013 1–7

Using PCFP 

0 0 

1 0 1 

2 0 

3 0 0 

4 

5 A 

6 

7 

8 B 

9 

10 0 0 

11 0 

12 0 0 

13 0 

14 0 0 

Figure 1–5. File Identifier Packet Items with Numeric Equivalents 

Procedure 5 

In languages other than COBOL, PCFP functions are called as functions. In COBOL, 

PCFP functions are called as subroutines, using the COBOL CALL statement. The 

DELETE_FILE function is called with two parameters: 

• The function packet 

• The file identifier packet 

After calling the PCFP function, your program should check the item ERROR_CLASS in 

the function packet to determine if the function produced an error. 

Procedure 6 

One suggested way of performing error processing is simply to display a message 

denoting the error. Note that the error code returned in the function packet is in ELMS 

format. This means that in order to get a true explanatory error message for the error 

code, your program (if written in C language) can call the Extended Message Language 

System (ELMS) with this error code as input. In Sections 11 – 13, the programs that 

implement this example simply display the error code along with an explanatory prefix. 

Procedure 7 

Before your program exits, you may want it to display a completion message to confirm 

that the operation PCFP was called to perform completed successfully. The programs in 

Sections 11 – 13 that implement this example display a simple completion message 

when no error is detected. 

1–8 7830 9796–013

1.3.2. Calling PCFP to Copy a File 

Using PCFP 

Figure 1–6 shows the process used to call a PCFP function that requires more setup 

than the DELETE_FILE function required. In this figure, PCFP is called to copy the 

contents of mass storage file A*B(2) to the mass storage file with an internal name of 

FILE2. Procedures 1 – 9 are explained following the figure. 

Figure 1–6. Calling the COPY_RAF_RAF Function 

7830 9796–013 1–9

Using PCFP 

Procedure 1 

Clear the function packet to zeros to ensure that each item in the function packet is set 

at its default value. This allows you to concentrate on the values you want to change. 

Procedure 2 

Set the necessary items in the COPY_RAF_RAF function packet: 

• Set INTERFACE_LEVEL to fp_interface_level_1 (1). 

• Set WORK_AREA_SIZE to fp_max_work_area_copy_raf_raf (60,000 is the maximum 

work area size for the COPY_RAF_RAF function). 



information to the calling program. For example, in Figures 1–7 and 1–8, the items 

PREVENT_OVERCOPY (a) and ZERO_RELEASED_STORAGE (b) in the specific part of 

the function packet are left initialized to FALSE, and the item STORAGE_TO_RELEASE is 

left initialized to none. 

Figures 1–7 and 1–8 compare the items of the COPY_RAF_RAF function packet to the 



1 a b 



4 


6 


8 ERROR_CODE 


10 a c STORAGE_TO_RELEASE 

11 AMOUNT_COPIED 

Figure 1–7. COPY_RAF_RAF Function Packet Items 

1–10 7830 9796–013

0 1 0 

1 F F 0 

2 60000 

3 0 

4 

5 0 

6 

7 0 

8 0 

9 0 

10 F 0 F 0 

11 0 

Using PCFP 

Figure 1–8. COPY_RAF_RAF Function Packet with Numeric Equivalents 

Procedure 3 

Clear the source file identifier packet to zero to ensure that each item in the packet is set 


Procedure 4 

Set the necessary items in the source file identifier: 


• Set QUALIFIER to A. 

• Set FILENAME to B. 

• Set F_CYCLE_TYPE to abs (1). 

• Set F_CYCLE to 2. 

You do not need to set the other items in the source file identifier packet, because the 

default value (0) is the desired value for these. 

Figures 1–9 and 1–10 compare the items of the source file identifier packet to the packet 

completed with the numeric and character equivalents for the items. 

7830 9796–013 1–11

Using PCFP 

0 




4 

5 QUALIFIER 

6 

7 

8 FILENAME 

9 


11 READ_KEY 

12 READ_KEY 

13 WRITE_KEY 

14 WRITE_KEY 

Figure 1–9. Source File Identifier Packet Items 

0 0 

1 0 1 

2 0 

3 0 0 

4 

5 A 

6 

7 

8 B 

9 

10 1 2 

11 0 

12 0 0 

13 0 

14 0 0 

Figure 1–10. Source File Identifier Packet Items with Numeric Equivalents 

1–12 7830 9796–013

Procedure 5 

Using PCFP 

Clear the destination file identifier packet to zero to ensure that each item in the packet 

is set at its default value. This allows you to concentrate on the values you want to 

change. 

Procedure 6 

Set the necessary items in the destination file identifier packet: 


• Set FILENAME to FILE2. 

You do not need to set the other items in the destination file identifier packet because 

the default value (0) is the desired value for these. 

The illustration of the destination file identifier packet is not shown here because it is 

similar to file identifier packets illustrated earlier. 

Procedure 7 

In languages other than COBOL, PCFP functions are called as functions. In COBOL, 

PCFP functions must be called as procedures, using the COBOL CALL statement. This 

function is called with three parameters: 


• The source file identifier packet 

• The destination file identifier packet 

After calling the PCFP function, your program should check the item ERROR_CLASS in 

the function packet to determine if the function produced an error. 

Procedure 8 

As suggested in the first example, a C language program can present the error code to 

ELMS to get an explanatory message that describes the error condition. In Sections 

11 – 13, the programs that implement this example display the error code along with an 

explanatory prefix. 

Procedure 9 

Before your program exits, you may want it to display a message that confirms the 

successful completion of the copy operation that PCFP was called to perform. In 

Sections 11 – 13, the programs that implement this example display a message denoting 

the number of tracks of data that were successfully copied. 

7830 9796–013 1–13

Using PCFP 

1.3.3. Calling PCFP to Acquire Element Information from a 

Program File 

Figure 1–11 shows the process used to call a PCFP function that requires a setup of the 

following: 

• Function and file identifier packet 

• The definition of an area to contain repeating return information 

In this example, PCFP is called to acquire all information about the symbolic elements in 

the program file A*B. A return area capable of accepting up to 100 return entries is 

made available to PCFP. Procedures 1 – 7 are explained following the figure. 

Figure 1–11. Calling the ACQ_ELT_INFO Function 

1–14 7830 9796–013

Procedure 1 

Using PCFP 

Clear the function packet to zeros to ensure that each item in the function packet is set 


Procedure 2 

Set the necessary items in the ACQ_ELT_INFO function packet: 


• Set WORK_AREA_SIZE to fp_max_work_area_acq_elt_info (20,000 is the maximum 

work area size for the ACQ_ELT_INFO function). 

• Set RTN_AREA_SIZE large enough for 100 element entries. (100 entries times the 

word length of the long form of the element return entry, which is 16). 

• Set SYM_TYPE (d) to TRUE. This indicates that PCFP is to select only symbolic 

elements. 

• Set INFO_DETAIL to long. This indicates that PCFP is to return the long form of 

element return entries. 



information to the calling program. In particular, the remaining items denoting element 

type selection [ABS_TYPE (a), OMN_TYPE (b), and REL_TYPE (c)] and the items denoting 

element subtype selection (arrays e and f) are left initialized to FALSE. This means that 

only symbolic element types are selected; and within this type, there is no subtype 

restriction. Thus PCFP selects all symbolic elements having any subtype. 

Figures 1–12 and 1–13 compare the items of the ACQ_ELT_INFO function packet to the 


7830 9796–013 1–15

Using PCFP 


1 a b 


3 

4 

5 

6 

SOFTWARE_LEVEL 

GEN_DATE_TIME 


8 ERROR_CODE 


10 

11 RTN_AREA_SIZE 

12 

13 NUM_RTN_ENTRIES 

14 

15 RTN_ENTRY_SIZE NUM_ENTRIES_IN_RTN_AREA 

16 

17 

18 

19 

20 

21 

22 

23 

24 

25 a b c d 

ELT_NAME 

ELT_VERSION 

26 e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e 


28 f f f f f f f f f f f f f f f f f f CHAR_TYPE 

29 

30 

31 

32 

MIN_DATE_TIME 

MAX_DATE_TIME 

Figure 1–12. ACQ_ELT_INFO Function Packet Items (cont.) 

33 MIN_SEQ_NUM 

1–16 7830 9796–013

34 MAX_SEQ_NUM 

35 MIN_SIZE 

36 MAX_SIZE 

37 DELETION INFO_DETAIL 

38 NUM_SELECTED 

39 

40 

41 

42 

Figure 1–12. ACQ_ELT_INFO Function Packet Items 

Using PCFP 

7830 9796–013 1–17

Using PCFP 

0 1 0 

1 F F 0 

2 2000 

3 

4 

5 

6 

7 0 0 0 

8 0 

9 0 

10 0 

11 1600 

12 0 

13 0 

14 0 

15 0 0 

16 0 

17 0 

18 0 

19 

20 

21 

22 

23 

24 

25 F F F T 

26 F F F F F F F F F F F F F F F F F F F F F F F F F F F F F F F F F F F F 

27 F F F F F F F F F F F F F F F F F F F F F F F F F F F F F F F F F F F F 

28 F F F F F F F F F F F F F F F F F F 0 

29 

30 

Figure 1–13. ACQ_ELT_INFO Function Packet Items with Numeric Equivalents 

(cont.) 

1–18 7830 9796–013 

0 

0 

0 

0 

0

31 

32 

33 0 

34 0 

35 0 

36 0 

37 0 1 

38 0 

39 0 

40 0 

41 0 

42 0 

Using PCFP 

Figure 1–13. ACQ_ELT_INFO Function Packet Items with Numeric Equivalents 

Procedure 3 

7830 9796–013 1–19 

0 

Clear the file identifier packet to zeros to ensure that each item in the packet is set at its 

default value. This allows you to concentrate on the values you want to change. 

Procedure 4 

Set the necessary items in the file identifier packet: 


• Set QUALIFIER to A. 

• Set FILENAME to B. 

You do not need to set the other items in the file identifier packet, because the default 

value of zero is the desired value for these. 

See Figures 1–4 and 1–5 for an illustration of the file identifier packet. 

Procedure 5 

This function is called with three parameters: 


• The file identifier packet 

• The return area 

After calling the function, your program should check the function packet to determine if 

any errors occurred.

Using PCFP 

Procedure 6 

As suggested in the other two examples, a C language program can present the error 

code to ELMS to get an explanatory message that describes the error condition. In 

Sections 11 – 13, the programs that implement this example display the error code along 

with an explanatory prefix. 

Procedure 7 

Before your program exits, you will want it to perform some processing of the 

information returned by PCFP in the return area. In Sections 11 – 13, the programs that 

implement this example display a header line denoting the number of elements selected 

using the item NUM_RTN_ENTRIES that PCFP returned in the function packet. 

Following this, the programs display a line for each element in the return area, showing 

its name, version, sequence number, and subtype name. 

1–20 7830 9796–013

1.4. Summary of PCFP Functions 

Using PCFP 

Table 1–1 presents a summary, in alphabetical order, of all the functions PCFP provides. 

The first column gives the function name. The second column gives a concise 

description of the function. The third column gives analogous FURPUR commands for 

users who are familiar with the FURPUR command language. Note that in most cases, 

the PCFP functions provide capabilities beyond those available in FURPUR. Also, in 

some cases capabilities of a FURPUR command are split across multiple PCFP functions. 

The fourth column gives the subsection of this manual that describes the PCFP function. 

You can refer to Appendix B. This appendix provides a complete list of FURPUR 

commands and options and the analogous PCFP function, when applicable. 

Function Name 

Table 1–1. Summary of PCFP Functions 

Description 

ACQ_BASIC_PF_INFO Returns global information about a specified program 

file. 

ACQ_ELT_INFO Returns information about a set of elements in a 

program file that satisfy specified criteria. 

ACQ_FILE_INFO Returns directory information about a single specified 

file. 

ACQ_FILE_LIST Returns directory information about a set of files that 

satisfy specified criteria. 

ACQ_OM_EP_INFO Returns information about a set of object- module 

entry points in a program file that satisfy specified 

criteria. 

ACQ_PROC_INFO Returns information about a set of procedures in a 

program file that satisfy specified criteria. 

ACQ_REL_EP_INFO Returns information about a set of relocatable entry 

points in a program file that satisfy specified criteria. 

CHG_ELT Changes attributes of a set of elements in a program 

file that satisfy specified criteria. 

CHG_FILE Changes directory attributes of a single specified 

cataloged file and initializes an empty file as a 

program file. 

CHG_FILE_CYC Changes the F-cycle limit for the files in a specified 

F-cycle series. 

CHG_FILE_KEYS Changes the read or write key for the files in a 

specified F-cycle series. 

CHG_FILE_NAME Changes the qualifier or file name for the files in a 

specified F-cycle series. 

Analogous 

FURPUR 

Command 

Sub- 

section 

@PRT,TL 6.1 

@PRT,TL 6.2 

@PRT,F 3.1 

@PRT,F 

@PRT,I 

7830 9796–013 1–21 

3.2 

@PRT,TL 6.4 

@PRT,TL 6.5 

@PRT,TL 6.3 

@CHG,AORS; 

@CYCLE 

@CHG,ET; 

@CHG,V; 

@CHG,W; 

@CHG,Z; 

@ENABLE 

8.1 

4.1 

@CYCLE 4.2 

@CHG 4.4 

@CHG,N 4.5

Using PCFP 

Function Name 

Table 1–1. Summary of PCFP Functions 

Description 

CHG_FILE_SEC Changes security attributes for the files in a specified 

F-cycle series. 

Analogous 

FURPUR 

Command 

@CHG,K; 

@CHG,P; 

@CHG,Q 

Sub- 

section 

CLOSE_SAF Writes a logical-end mark to a tape file. @MARK 10.2 

COPY_ELT Copies a set of elements that satisfy specified criteria 

from one program file to another. 

COPY_OMN_ELT_RAF Copies a single omnibus element from a program file 

to a mass storage file. 

COPY_RAF_OMN_ELT Creates a single omnibus element in a program file 

from the contents of a mass storage file. 

COPY_RAF_RAF Copies the contents of one mass storage file into 

another mass storage file. 

COPY_RAF_SAF Copies the contents of one mass storage file into a 

tape file. 

COPY_RAF_SYM_ELT Creates a single symbolic element in a program file 

from the contents of a mass storage file containing 

SDF text. 

COPY_SAF_RAF Copies a single logical file from a tape file to a mass 

storage file. 

COPY_SAF_SAF Copies a single logical file from one tape file to 

another tape file. 

COPY_SYM_ELT_RAF Copies a single symbolic element from a program file 

to a mass storage file. 

DELETE_ELT Deletes a set of elements in a program file that 


@COPY,P; 

@COPY,AORS 

1–22 7830 9796–013 

4.3 

7.1 

@COPY,IO 7.4 

@COPY,IO 7.5 

@COPY 5.1 

@COPY,G 5.2 

@COPY,I 7.3 

@COPY,G 5.3 

@COPY 5.4 

@COPY,I 7.2 

@DELETE,AORS; 

@PACK,AORS 

DELETE_FILE Deletes a single file. @DELETE 9.2 

ERASE_RAF Releases or zero-fills mass storage in a file. @ERS 9.1 

MOVE_SAF Repositions a tape file. @MOVE; 

@REWIND 

PACK_PF Releases dead space due to deleted elements from a 

program file. 

8.2 

10.1 

@PACK 8.4 

PREP_PF Creates entry point tables in a program file. @PREP 8.5 

UNDELETE_ELT Undeletes a set of elements in a program file that 


@DELETE,UAORS 8.3

1.5. PCFP Processor 

Using PCFP 

The PCFP level and PCFP generation date and time are returned by PCFP to the calling 

program in each function packet (see 2.4.1). However, this information is not visible to 

the user unless the calling program formats and displays it. 

The PCFP processor provides a convenient method of displaying the PCFP level and the 

PCFP generation date and time from within an OS 2200 runstream. Call the PCFP 

processor with the following command: 

@PCFP 

The PCFP processor displays a processor identification line in the following format: 

PCFP level (yymmdd hhmm:ss) yyyy mmm dd dow hhmm:ss 

where: 

level 

is the PCFP level. 

yymmdd hhmm:ss 

is the PCFP generation date and time. 

yyyy mmm dd dow hhmm:ss 

is the current date and time. 

The PCFP processor displays the PCFP copyright notice and the following termination 

line: 

END PCFP. 

7830 9796–013 1–23

Using PCFP 

1–24 7830 9796–013

Section 2 

Functions of PCFP 

This section describes the following information about PCFP functions: 

• The general form of all functions that are part of PCFP 

• The data types used in this manual to describe the parameters passed to and from 

PCFP functions 

• The detailed definitions of certain parameters and parts of parameters that are used 

by most PCFP functions 

The information presented in this section is not language dependent. Certain special 

considerations exist for each language from which you can call PCFP. Consult the 

appropriate section (11, 12, or 13) for these special considerations. 

2.1. Typical Form of PCFP Functions 

In C and FORTRAN, each PCFP function is a subroutine that is called as a function with 

parameters. In COBOL, each PCFP function is called as a subroutine with parameters. 

All PCFP parameters are data structures that contain a number of data items. Before 

calling PCFP, the calling program sets the data items in the parameters for the precise 

task to be performed by the function. When the calling program calls a PCFP function, 

PCFP passes back the results of the task in the parameters and the function-return 

value. The calling program examines these return values after it calls PCFP. The 

parameters are discussed later in this subsection. 

Each parameter structure used by PCFP is defined in this manual. Each structure is 

defined in a diagram giving the layout of the structure and names of the items contained 

in the structure. A list of the items follows each diagram, giving the name of the item, 

its data type, the list of values that the item can assume (where applicable), and a short 

description of the item. For the most part, the names of items and values are the same 

across all languages from which PCFP can be called. However, language-specific 

differences are necessary in some cases, and are described in Sections 11 – 13. 

7830 9796–013 2–1


The following are parameters that most PCFP functions use: 

• Function Packet 

This structure is the first parameter of each PCFP function. It acts both as an input 

parameter and an output parameter. It is the structure through which the calling 

program specifies all options that apply to the function. PCFP also uses this 

parameter to pass certain fixed-sized return items back to the calling program. The 

function packet for each function consists of generic parts, which are the same for 

many or all functions, and a specific part, which contains items specific to the 

individual function. The generic parts of the function packet are described in 2.4.1 

and 2.4.2. The specific parts are described in Sections 3 – 10. 

• File Identifier 

This input parameter is a structure that uniquely identifies a file to be operated on by 

a function. Functions that do not operate on an individual file have no parameter of 

this type. Functions that operate on a single file have a single file-identifier 

parameter. Copy functions, which operate on two files at once, have two 

file-identifier parameters: one for the source file from which data is copied, and one 

for the destination file, to which data is copied. The file identifier parameter is 

described in 2.3. 

• Return Area 

Some functions return to the calling program information about a list of files or 

elements. These functions return a variable-length array of return entries, one entry 

for each file or element in the list. For these functions, the calling program must 

supply an output parameter, called the return area, into which PCFP places as many 

of the return entries as will fit into this area. The calling program specifies the size of 

this return area parameter in the function packet. 

• Work Area 

Each PCFP function requires a scratch data area, called the work area, in which to do 

its calculations. For this release of PCFP, the calling program does not supply this 

parameter; PCFP allocates and releases it dynamically. (In COBOL and FORTRAN 

programs, this parameter is omitted; in C programs, you must specify the value 

NULL for this parameter.) However, the calling program must specify the size of the 

work area that PCFP allocates. The function descriptions in Sections 3 – 10 indicate 

the work area size requirements for each function. 

The function value returned by each PCFP function (in C and FORTRAN) is an ELMS 

condition-id. This condition-id indicates if the function completed successfully or, if it did 

not complete successfully, why not. 

2–2 7830 9796–013


All of the above parameters are moved to a dynamic basic mode bank where they are 

operated on by PCFP. In addition to these parameters, PLUS stack space and PLUS 

work space are also allocated in the dynamic bank. The maximum possible size of the 

dynamic basic mode bank limits the maximum size that can be specified for the return 

area and the work area. The maximum size for most PCFP functions is the difference 

between the minimum relative address, defined by MIN_DATA_ADDR, and the 

maximum relative address, defined by MAX_DATA_ADDR. These definitions are 

contained in the copy/include element FP$DEFS. Some functions require a different 

minimum relative address or a different maximum relative address. In these cases the 

function descriptions in Sections 3 – 10 indicate the minimum and maximum addresses 

that apply for the function. 

2.2. Data Types 

The following data types are used in the item descriptions throughout this manual. 

These data types are described here in a language-independent manner. Any 

language-specific considerations are described in Sections 11 – 13. 

Character 

The item contains an ASCII character string, the maximum length of which is given in the 

item description. The calling program must specify character values shorter than the 

maximum by one of the following means: 

• Left-justified within the item, and space-filled on the right. This is the typical method 

for specifying strings in languages other than C. 

• Left-justified within the item, and null-terminated on the right. (Null-terminated 

means that the string is followed immediately by a null character [integer code 0], 

and that all characters following the null are insignificant.) This is the typical method 

for specifying strings in C. 

Either of these methods can be used by a calling program written in any language. It is 

permissible for some strings to be specified using one method, and others to be 

specified using the other method. 

In character items input to PCFP, both uppercase and lowercase letters are allowed. 

PCFP treats each lowercase letter as its uppercase equivalent except where noted 

otherwise. In character items returned by PCFP, letters are uppercase only, except 

where noted otherwise. 

Integer 

The item may assume integer values. In some cases, “unsigned” is also specified to 

indicate that only nonnegative integer values are legal. Unless the range of integer 

values that can be assumed by the item is particularly important, it is not noted in the 

item description (but can be inferred from the structure layout). Integer items are 

allocated with sizes large enough so that the size of the item poses no significant 

restriction on the capabilities of PCFP. 

Condition 

The item can assume only the values TRUE and FALSE. Internally, TRUE is represented 

by 1, and FALSE is represented by 0. 

7830 9796–013 2–3


Condition Array 

A condition array is a contiguous grouping of related 1-bit condition items. Individual 

condition items are numbered from left to right in increasing order, usually starting with 

0. Specify the condition item number as a subscript of the condition array name to 

identify an individual condition item in the array. For example, if ABS_SUBTYPE is a 

condition array of 18 condition items, the first (left-most) condition item would be 

identified as ABS_SUBTYPE(0) and the last (right-most) condition item would be 

identified as ABS_SUBTYPE(17). 

Value-List 

The values the item can assume are listed explicitly. (Each value is a named constant 

followed by its internal integer code.) The structure definitions supplied with PCFP 

include definitions for the enumerated constants. 

The value represented by zero internally is chosen to be the one that is likely to be used 

most frequently. This allows a programmer to zero fill an entire packet containing many 

items and to fill in only those items that are applicable to the task. In those cases where 

the value-list does not have a legal value for zero, the calling program must always set 

the item explicitly. 

Date-Time 

The item can assume values representing date and time. Each item with this data type 

is two words long, and contains the following items: 

• Year: unsigned integer in H1 of first word. Contains the year part of the date. 

• Month: unsigned integer range (1 – 12) in Q3 of first word. Contains the numeric 

value of the month part of the date. 

• Day: unsigned integer range (1 – 31) in Q4 of first word. Contains the numeric value 

of the day-of-the-month part of the date. For the COBOL language only, this item is 

named DAY-OF-MONTH to avoid conflict with the COBOL reserved word DAY. 

• Milliseconds: unsigned integer range (0 – 86,399,999) in second word. Contains the 

time past midnight in milliseconds. All time values returned by PCFP are rounded to 

the nearest second, so when an item of this type is returned by PCFP, it is always 

divisible by 1,000. 

In addition to these individual items, a method is provided in each language to compare 

date-time values as entire entities. These methods are described in Sections 11 – 13. 

2.3. File Identifiers 

PCFP functions that operate on a specific file (or two specific files) must have a file 

identifier that uniquely names each file that the function is to operate upon. For the sake 

of consistency, the file identifier used by all PCFP functions has the same format. This 

subsection explains all the items contained in this file identifier. See Figure 2–1. 

The file identifier contains the following four items that uniquely identify a file: 

• Directory-id 

2–4 7830 9796–013

• Qualifier 

• File name 

• F-cycle 


In addition to these items, the file identifier contains an interface level number, an Fcycle 

type, which denotes the type of F-cycle (absolute, relative, unspecified) that is 

specified, and read/write keys. 

In the file identifier, all defined items contain values that the calling program inputs to 

PCFP. Those parts of the file identifier for which no item is defined must contain zero 

when PCFP is called. PCFP never alters any part of a file identifier parameter. Thus, the 

same file identifier can be input to multiple functions that are to operate on the same file. 

Before calling a PCFP function, the calling program must initialize its file identifier 

parameters (if any). The calling program should do this first by zero-filling the entire 

structure. Sections 11 – 13 describe a method for doing this for each language from 

which PCFP can be called. 

The file identifier structure is defined in copy/include element FP$FILE$ID. This element 

must be included in any program that calls a PCFP function. 

0 




4 

5 QUALIFIER 

6 

7 

8 FILENAME 

9 


11 READ_KEY 

12 READ_KEY 

13 WRITE_KEY 

14 WRITE_KEY 

Figure 2–1. File Identifier Packet Items 

7830 9796–013 2–5


Item Descriptions 

INTERFACE_LEVEL 

Indicates the interface level of structure definitions used to code this call to PCFP. 

The calling program must set this item to the value FP_INTERFACE_LEVEL_1. 

Data Type: unsigned integer 

DIRECTORY_ID 

Indicates the name of the directory in which the file is defined. Currently, the only 

legal values are the character strings STD and SHARED. A null value indicates the 

default directory for the run, while a value of spaces indicates the implied directory 

for the run. 

Note that the default directory for a run is set by using the Exec command @QUAL 

with the D option, while the implied directory for the run is set by using the @QUAL 

command with no option specified. 

Data Type: characters (6) 

QUALIFIER 

Indicates the qualifier for the file. A null value indicates the default qualifier for the 

run. A value of all spaces indicates the implied qualifier for the run. 

Note that the default qualifier for a run is set by using the Exec command @QUAL 

with the D option. The implied qualifier for a run is set by using @QUAL with no 

option specified. 


FILENAME 

Indicates the basic name of the file, which the calling program must always specify. 

If all items in the file identifier structure other than INTERFACE_LEVEL and 

FILENAME are zero or null, PCFP interprets the file name as an internal name of a 

file already assigned or known to the run. 


2–6 7830 9796–013

F_CYCLE_TYPE 


Indicates whether F_CYCLE contains an absolute F-cycle value, a relative F-cycle 

value, or no F-cycle value. 

Data Type: value-list 

UNSPECIFIED = 0 

An F_CYCLE_TYPE of UNSPECIFIED refers to the latest F-cycle of an F-cycle 

series, except for functions that apply to an entire F-cycle series (these are 

CHG_FILE_CYC, CHG_FILE_SEC, CHG_FILE_KEYS, and CHG_FILE_NAME). For 

the functions that apply to an entire F-cycle series, the calling program must set 

this item to UNSPECIFIED. 

ABS = 1 

REL = 2 

F_CYCLE 

Indicates the F-cycle of the file. If the calling program sets F_CYCLE_TYPE = 

UNSPECIFIED, it must set this item to 0. If the calling program sets F_CYCLE_TYPE 

= ABS, it must set this item to a value between 1 and 999 inclusive. If the calling 

program sets F_CYCLE_TYPE = REL, it must set this item to a value between -31 

and 1 inclusive. 

Data Type: signed integer range (-31 through 999) 

READ_KEY 

Indicates the read key that PCFP is to use to assign the file. If the calling program 

supplies a null value for this item, PCFP uses no read key when it attempts to assign 

the file. If the file is already assigned prior to calling PCFP, PCFP ignores this item. 


WRITE_KEY 

Indicates the write key that PCFP is to use to assign the file. If the calling program 

supplies a null value for this item, PCFP uses no write key when it attempts to 

assign the file. If the file is already assigned prior to calling PCFP, PCFP ignores this 

item. 


7830 9796–013 2–7


2.4. Function Packet 

The function packet acts as both an input and an output parameter. It is a structure 

through which the calling program specifies all options that apply to the function. This 

same structure is also used by PCFP to pass certain fixed-size return items back to the 

calling program. 

The function packet contains the following parts: 

• A generic part, which is the same for all functions, is specified at the start of each 

function packet. This part is described in 2.4.1. 

• A return-information part, which describes the return area used by the function. This 

part of the function packet exists only for those functions that have a return area 

parameter. This part is described in 2.4.2. 

• A specific part, which contains items specific to the individual function. The specific 

part of each function packet is described in Sections 3 – 10. 

In the function packet descriptions, those items that are explicitly labeled as “returned” 

contain values that PCFP returns to the calling program. These are the only items in the 

function packet that PCFP alters. All other items contain values that the calling program 

inputs to PCFP. PCFP examines only the input items from the function packet. The 

function packets also contain areas for which no item is defined; the calling program 

must initialize these areas to zero before calling PCFP. 

Before calling a PCFP function, the calling program must set up the function packet. The 

program does this first by zero-filling the entire structure. Sections 11 – 13 describe a 

method for doing this for each language from which PCFP can be called. Next, the 

calling program must explicitly set each input item in the packet for which a value of zero 

is not the desired value. 

2.4.1. Generic Part of the Function Packet 

The generic part of the function packet is the first part of the function packet for every 

PCFP function. To reduce repetition, the description of this part appears once here, and 

is not repeated in the descriptions of the individual functions. This part of the function 

packet must be initialized by the calling program before every call to a PCFP function. 

2–8 7830 9796–013


The structure of this part is defined in copy/include element FP$GENERIC. This element 

must be included in your program before any copy/include element that defines a 

specific function packet. See Figure 2–2. 


1 a b c 



4 


6 


8 ERROR_CODE 




Figure 2–2. Generic Part of the Function Packet 

Indicates the level of data structure definitions used for this function. All PCFP 

functions initially use a value of FP_INTERFACE_LEVEL_1. As new features are 

implemented for a function, it is sometimes necessary to expand the data structures 

(function packet, return entries and/or other special return information). When this 

occurs, the function packet interface level is increased by 1. The individual function 

packet documentation in Sections 3 – 10 describes the most current interface level 

for each function that supports interface levels other than FP_INTERFACE_LEVEL_1. 

The interface level is changed to ensure compatibility for existing function calls. 

Existing programs with older interface levels continue to operate correctly with no 

program changes. To use the new features, it is necessary to modify the program to 

use the new interface level and the associated new data structures. 

It is recommended that new programs and new function calls always use the most 

current interface level for each function. Data structures shown in this manual 

always correspond to the most current interface level. Data structures for older 

interface levels are shown in comments in the associated copy/include elements. 


7830 9796–013 2–9


a = WAIT_ON_FACILITIES 

Indicates whether PCFP should wait on facilities (if this is necessary to perform the 

function requested). If the calling program sets this item to TRUE, PCFP waits 

indefinitely for the facilities required to perform the function. If the calling program 

sets this item to FALSE, PCFP returns with an error condition if all required facilities 

are not immediately available. 

Data Type: condition 

b = NULL_TERM_STRINGS 

Indicates if all strings shorter than their maximum length that PCFP returns to the 

calling program are to be null-terminated instead of space-filled. This item is typically 

set to TRUE by a calling program written in C. This item does not effect handling of 

strings the calling program inputs to PCFP; strings input to PCFP can be either 

null-terminated or space-filled regardless of this item. 

Note: Any string returned by PCFP that is at maximum length (that is, entirely fills 

the item containing it) is not null-terminated. 


c = QUESTION_MARK_MATCHES_SPACE 

Indicates that the question mark ( ? ) wild-card character is allowed to match a space 

character. See 2.6 for a description of how wild-card characters can be used. 

WORK_AREA_SIZE 

Indicates the size (in words) of the work area that PCFP allocates to perform its 

work. The size requirements for each function are given in Sections 3 – 10 along 

with the description of the function. The total of WORK_AREA_SIZE and 

RTN_AREA_SIZE should not exceed approximately 238,000 words. As described in 

Sections 3 – 10, some functions have totals that are less than 238,000 words. 


SOFTWARE_LEVEL 

Returns the level of PCFP software that processed the function call. 

Data Type: characters (8), returned 

GEN_DATE_TIME 

Returns the date and time at which the PCFP software processed the function call. 

Data Type: date-time, returned 

2–10 7830 9796–013

ERROR_CLASS 


Indicates what class of error, if any, occurred when PCFP attempted to process the 

function. In all cases, the specific nature of the special circumstance, warning, or 

error is given by item ERROR_CODE. 

Data Type: value-list, returned 

NONE = 0 

Indicates the function completed with no problems. 

WARNING = 1 

Indicates the function completed, but some special circumstance or minor 

problem occurred. 

EXECUTION_ERROR = 2 

Indicates that PCFP attempted the function but did not complete it because of a 

problem encountered during execution. 

CALLER_ERROR = 3 

Indicates that PCFP did not attempt the function because the calling program did 

not set up a parameter properly. This class of error typically results from a bug 

in the calling program. 

ASG_ERROR = 4 

ERROR_FILE 

Indicates that PCFP could not assign one of the specified files for some reason. 

Indicates which file, if any, was the source of the warning or error that PCFP 

encountered. If your program calls ELMS to print an error message, it should supply 

this value as the second numeric insert. 


NONE = 0 

PCFP returns a value of NONE for this item if ERROR_CLASS = NONE, or if the 

error PCFP encountered is not associated with any specific file. 

TEMP_FILE = 1 

The value TEMP_FILE refers to a temporary file that PCFP may assign as part of 

its internal function processing. 

7830 9796–013 2–11


SOURCE_FILE = 2 

The value SOURCE_FILE refers to the source file for a copy function; it also 

refers to the only file for those functions that operate on a single file. 

DEST_FILE = 3 

The value DEST_FILE refers to the destination file of a copy function. 

SUB_ERROR_CODE 

Indicates the specific code (if any) associated with a warning or error that occurred 

when a PCFP function called another PCFP function as part of its processing and the 

called function (subfunction) encountered an error. The ERROR_CODE of the 

subfunction, without the ELMS severity code and component identifier code, is 

stored in SUB_ERROR_CODE. If your program calls ELMS to print error messages, 

it can supply this value as the third numeric insert. See Appendix A for a full 

description of handling SUB_ERROR_CODE using ELMS. 

Data Type: unsigned integer, returned 

ERROR_CODE 

Indicates the specific code associated with the warning or error that occurred while 

PCFP processed the function. This same value is also returned as the 

function-return-value in those languages (C and FORTRAN) that allow function-type 

procedure definitions. A value of FP_ERR_NONE (0) is returned if ERROR_CLASS = 

NONE. Because ERROR_CODE is an ELMS condition identifier, the calling program 

(if written in C) can call ELMS with this value to cause an appropriate error message 

to be printed. 

See Appendix A for a full list of the error codes that PCFP can return. See Sections 

11 – 13 for further information on handling error codes. 

Data Type: ELMS condition identifier, returned 

AUX_ERROR_CODE 

Indicates auxiliary error information (if any) associated with the error condition 

identified by ERROR_CODE. Typically, this value is an I/O status, an Executive 

request error code, or a facilities error code. For each ERROR_CODE for which 

AUX_ERROR_CODE is not applicable, PCFP sets AUX_ERROR_CODE to zero. If 

your program calls ELMS to print an error message, it should supply this value as the 

first numeric insert for the message. 


2–12 7830 9796–013

2.4.2. Return-Information Part of the Function Packet 


The return-information part of the function packet is the second part of the function 

packet for every PCFP function that can return repeating information. This 

return-information part follows immediately after the generic part. 

To reduce repetition, the description of this part appears once here, and is not repeated 

in the descriptions of the individual functions. This part of the function packet must be 

initialized by the calling program before calling every PCFP function that can return 

repeating information. 

The structure of this part is defined in the copy/include element FP$RTN$INFO. This 

element must be included in your program before any included element that defines a 

specific function packet that allows return information. See Figure 2–3. 

0 

1 RTN_AREA_SIZE 

2 

3 NUM_RTN_ENTRIES 

4 

5 RTN_ENTRY_SIZE NUM_ENTRIES_IN_RTN_AREA 

6 

7 

8 

Figure 2–3. Return-Information Part of the Function Packet 


RTN_AREA_SIZE 

Indicates the size (in words) of the return area through which PCFP returns repeating 

information to the calling program. The calling program must supply a value of zero 

for this item if the calling program supplies no return area (that is, if the return area 

parameter in the argument list of the function call is null). The total of 

WORK_AREA_SIZE and RTN_AREA_SIZE should not exceed approximately 238,000 

words. As described in Sections 3 – 10, some functions have totals that are less 

than 238,000 words. 


NUM_RTN_ENTRIES 

Indicates the total number of return entries produced by the function, including those 

that did not fit in the return area. 


7830 9796–013 2–13


RTN_ENTRY_SIZE 

Indicates the size of each return entry produced by the function. If all entries 

produced by the function are not the same size, this item has a value of zero. 


NUM_ENTRIES_IN_RTN_AREA 

Indicates the number of return entries that fit into the return area supplied by the 

calling program. This item is zero if PCFP placed no return entries in the return area. 

2.5. Work Area 


The work area is a scratch data area used by PCFP to do its calculations. The calling 

program does not supply this parameter. PCFP allocates and releases it dynamically. (In 

COBOL and FORTRAN programs, this parameter is omitted; in C programs, you must 

specify the NULL value for this parameter.) However, the calling program must specify 

the size of the work area that PCFP is to allocate. The function descriptions in Sections 

3 – 10 describe the work area size requirements for each function. 

The copy/include element for each function defines a minimum and a maximum work 

area size for the function. The calling program must always supply a work area no 

smaller in size than the minimum. The calling program can supply a work area larger 

than the maximum, but PCFP may not be able to use an area greater than the maximum. 

For a few functions, there are instances for which PCFP can use a work area larger than 

the defined maximum, usually to improve function performance. These exceptions are 

described in Sections 3 – 10. The total size of the work area and the return area should 

not exceed approximately 238,000 words. This is the approximate maximum size that 

can be specified for most PCFP functions, where the minimum relative address is 

MIN_DATA_ADDR and the maximum relative address is MAX_DATA_ADDR, as 

contained in the copy/include element FP$DEFS. 

2–14 7830 9796–013

2.6. Wild-Card Characters 


Some PCFP functions allow your program to specify partial names (for example, file 

names, qualifiers, element names, element versions). If you specify a partial name, any 

object whose name matches the partial name can qualify to be operated on by that 

function. You specify partial names through the use of 2 special characters, sometimes 

called wild-card characters. The 2 characters are 

• Question mark ( ? )—This character can match a single character. When the item 

QUESTION_MARK_MATCHES_SPACE in the generic part of the function packet is 

set to its default value of FALSE, the ? character matches any single character 

except a space character. When the item is set to TRUE, the ? character matches 

any single character. See 2.4.1 for a description of the 

QUESTION_MARK_MATCHES_SPACE item. 

• Asterisk ( * )—This character can match any string of zero or more characters. 

The following examples show how you might use these characters: 

• The partial name ABC?DEF matches any 7-character name starting with ABC and 

ending with DEF. 

• ABC??? matches any 6-character name starting with ABC when 

QUESTION_MARK_MATCHES_SPACE is FALSE. It matches any 3-character to 

6-character name starting with ABC when QUESTION_MARK_MATCHES_SPACE is 

TRUE. 

• A?C?E matches any 5-character name starting with A, with C in the third position, 

and with E in the last position. 

• ABC* matches any name of 3 or more characters starting with ABC. 

• AB*YZ matches any name of 4 or more characters starting with AB and ending with 

YZ. 

• A*56*Z matches any name of 4 or more characters starting with A, ending with Z, 

and with 56 somewhere in the middle. 

• * matches any name of any length. Typically, your program can achieve the same 

effect more efficiently by leaving the character string with its initial value of null. 

• AB??* matches any name of 4 or more characters starting with AB when 

QUESTION_MARK_MATCHES_SPACE is FALSE. It matches any name of 2 or more 

characters starting with AB when QUESTION_MARK_MATCHES_SPACE is TRUE; 

this would be equivalent to specifying AB*. 

• A?C*Z* matches any name of 4 or more characters, with A in the first position, C in 

the third position, and Z somewhere following the third position. 

• ??????* matches any name of 6 or more characters when 

QUESTION_MARK_MATCHES_SPACE is FALSE. It matches any name of any 

length when QUESTION_MARK_MATCHES_SPACE is TRUE; this would be 

equivalent to specifying *. 

7830 9796–013 2–15


The question mark character is also allowed by some functions in the name of the result 

object produced by that function. In such a case, the character PCFP actually places in 

the corresponding position of the result name is the character in the same position in the 

name of the input object. When the question mark character is used in this way, it can 

be replaced by a space character from the input object. The setting of the 

QUESTION_MARK_MATCHES_SPACE item does not affect this operation. 

This facility is most useful when a series of objects is to be created (or their names 

altered) using a function. As an example, you might want to change the names of all 

elements in a program file, so that the first 3 characters of the names are XYZ, while the 

remaining characters in the names are unchanged. Using the partial name XYZ????????? 

as the new element name accomplishes this. 

2.7. Function-Specific Interface Information 

Sections 3 – 10 define the aspects of the interface that are specific to each function. 

These aspects include the following: 

• A general description of what the function does, and what options are available. 

• The number and order of the parameters for the function, and the meaning of each 

parameter. In many cases, the parameters are described by referring to one of the 

general parameter categories listed in 2.1. 

• The name of the copy/include element associated with the function. 

• The physical layout and items contained in the specific part of the function packet for 

the function. (Note that the offsets of items in the specific part of the function 

packets are always shown starting at 0, even though these items are always 

preceded by the generic part, and in some cases, the return-information part, of the 

function packet.) 

• The INTERFACE_LEVEL to use with this function, if it is other than 

FP_INTERFACE_LEVEL_1. 

• The physical layout and items contained in each return entry (if any) that can be 

returned by the function. 

• The work area requirements of the function. 

2–16 7830 9796–013

2.8. Multi-Activity Programs 


In general, you can call PCFP functions from multiple activities running in the same 

program. The following are general considerations for multi-activity programs: 

• Each activity must have its own function packets, file identifiers, and return area. 

• The activity does not need to allocate a work area. PCFP is responsible for 

dynamically allocating the basic mode bank that is used for the work area for each 

activity. 

• The program must ensure that a file is not operated on by more than one activity. 

For PCFP functions that operate on more than one file (for example, COPY_ELT), the 

program must ensure that none of the files are operated on by another activity. 

Exclusive use of files does not apply to different activities of the same program and 

cannot be used to bypass this consideration. 

Special restrictions apply when calling the ACQ_FILE_INFO and ACQ_FILE_LIST 

functions from multi-activity programs. This is because these functions directly examine 

the Program Control Table (PCT), which is shared by all program activities. When 

multiple activities call PCFP functions, the PCT is extremely volatile during the periods 

when PCFP attaches internal filenames to files, assigns files to the run, and frees 

internal filenames and files from the run. The restrictions are as follows: 

• Activities that call these functions must use program-level locks to ensure that while 

a ACQ_FILE_INFO or ACQ_FILE_LIST function is active, no other activity is calling 

any PCFP function. 

• Similarly, while these functions are active other activities cannot make facility 

requests that add internal or external filenames to the run or that remove internal or 

external filenames from the run. Also, calls to subsystems that make facility 

requests should not be allowed. 

• If proper locking procedures are not followed, the following may result: 

− The functions may return a fp_err_bad_pct_name_section error, with decimal 

error code 2145. 

− A Guard Mode (IGDM) contingency may occur in bank PCFP$3. 

− The return information entry may contain incorrect information. The internal 

filename information returned in the Run Assignment Part (see 3.1.4.7) is 

particularly vulnerable to incorrect information. 

− For the ACQ_FILE_INFO function, the return information entry may be for a file 

different than the one specified in the file identifier. 

− For the ACQ_FILE_LIST function, return information entries may be returned for 

files that should not have been selected by function packet specifications. 

Conversely, return information entries may not be returned for files that should 

have been selected. 

7830 9796–013 2–17


2–18 7830 9796–013

Section 3 

Acquiring General File Information 

This section describes the following two PCFP functions that obtain directory information 

about one or more files: 

• Acquire File Information (ACQ_FILE_INFO) acquires information about a single file 

specified by the calling program. 

• Acquire File List (ACQ_FILE_LIST) acquires similar information about all files that 

meet selection criteria specified by the calling program. 

3.1. Acquire File Information (ACQ_FILE_INFO) 

The ACQ_FILE_INFO function returns information about a single specified file. At a 

minimum, this function returns to the calling program the full external identifier of the file 

in question, with the exception of the read and write keys that might be attached to the 

file. This returned information is useful if the calling program originally identified the file 

by means of a use name. This function returns the file identifier even for a file that does 

not exist (one that is neither assigned to the run nor cataloged). 

You can also use this function to acquire additional information about a file (for example, 

ownership, F-cycles, mass storage allocations, tape characteristics, and usage 

restrictions). The calling program indicates in the function packet which of this 

information PCFP returns. The full list of information obtainable by using this function is 

detailed under the description of the return information for this function. 

This function does not cause an unloaded mass storage file to be loaded. 

3.1.1. Parameters 

The ACQ_FILE_INFO function has the following parameters, each of which is described 

in the following subsections: 



• Return Information 

• Work Area 

3.1.2. Function Packet 

The structure of the ACQ_FILE_INFO function packet is defined in element 

FP$ACQFILINF. See Figure 3–1. 

7830 9796–013 3–1


GENERIC PART 

RETURN-INFORMATION PART 

0 INFO_DETAIL b c d e 



Figure 3–1. ACQ_FILE_INFO Function Packet Items 

Contained in the GENERIC PART of the function packet and indicates the level of the 

packet. The calling program should set this item to the value 

FP_INTERFACE_LEVEL_2. If this item is set to FP_INTERFACE_LEVEL_1, the long 

form return information has a format different than that described in 3.1.4 and 3.1.5. 


INFO_DETAIL 

Indicates the subset of information that PCFP returns for the file. 


SHORT = 0 

Indicates that PCFP returns only the file identifier for each file. 

LONG = 1 

Indicates that PCFP returns information beyond the file identifier, including any 

subsets of information indicated by the items RTN_VOL_INFO, 

RTN_SECURITY_INFO, RTN_RUN_ASG_INFO, and RTN_EQUIP_MNEMONIC. 

COMPLETE = 2 

Indicates that PCFP returns all information obtainable through this function. 

When the calling program sets INFO_DETAIL to COMPLETE, the calling program 

receives the same information that it would receive by setting INFO_DETAIL to 

LONG, and RTN_VOL_INFO, RTN_SECURITY_INFO, RTN_RUN_ASG_INFO, 

RTN_EQUIP_MNEMONIC all to TRUE. 

The description of the return entry in 3.1.4 and 3.1.5 indicates the items included 

in each of the subsets above. 

b = RTN_VOL_INFO 

3–2 7830 9796–013


Indicates whether the function returns volume information for the file, if the file has 

volume information. (Only tape files and mass storage files on removable disk can 

have volume information.) This item is ignored unless INFO_DETAIL = LONG. 


c = RTN_SECURITY_INFO 

Indicates whether the function returns security information for the file, if the file has 

security information. (Only cataloged files can have security information.) This item 

is ignored unless INFO_DETAIL = LONG. 


d = RTN_RUN_ASG_INFO 

Indicates whether the function returns run-assignment information for the file. (Only 

a file assigned to the run of the calling program, or given a use name by that run, can 

have run-assignment information.) This item is ignored unless INFO_DETAIL = 

LONG. 


e = RTN_EQUIP_MNEMONIC 

Indicates that the function returns the equipment mnemonic for the file. This item is 

ignored unless INFO_DETAIL = LONG. 


3.1.3. File Identifier 

The file identifier parameter names the file this function operates on. See 2.3 for a 

detailed description of this parameter. 

7830 9796–013 3–3


3.1.4. Return Information (C Language) 

The structure of the return information parameter is defined in element FP$RTN$FILE. 

Upon successful completion of the ACQ_FILE_INFO function, PCFP creates one return 

entry. The contents of this return entry vary depending on what the calling program has 

requested in the function packet, and on the type of file the entry describes. Also, the 

structure of the return entry varies, depending on the language in which the calling 

program is written. 

For C programs, ACQ_FILE_INFO produces a variable-size entry, which is described 

next. 

For the variable-size form of the return entry, the size of the entry is given by the item 

RTN_ENTRY_SIZE in the return-information part of the function packet, and also by the 

item FULL_ENTRY_SIZE in the return entry itself. 

If the size of the return area specified by RTN_AREA_SIZE is not sufficient to contain the 

complete return entry, error code fp_err_small_return_area (decimal 1062) is returned in 

the function packet ERROR_CODE item. No information is returned, and the function 

packet RTN_ENTRY_SIZE and NUM_ENTRIES_IN_RTN_AREA items contain zeroes. 

Because various parts of this return entry are optional and not a fixed size, it is not 

possible for all items in the return entry to be at a fixed offset from the start of the entry. 

To handle this, the entry contains a number of offset items that give the offsets to the 

floating parts of the entry. Within each floating part, item locations are defined from the 

start of the part, not from the start of the entire entry. An offset value of zero indicates 

that the corresponding part of the entry is not present in this instance of the entry. 

Note: Figure 3–5 shows the new format long form information that is returned when 

INTERFACE_LEVEL has a value of at least FP_INTERFACE_LEVEL_2. 

3–4 7830 9796–013

3.1.4.1. Nonfloating Part 


Following is the layout of the nonfloating part of the return entry for ACQ_FILE_INFO. 

As indicated in the item descriptions that follow, only words 0 – 11 are present when the 

calling program has set INFO_DETAIL to SHORT in the function packet. See Figure 3–2. 

0 




4 

5 QUALIFIER 

6 

7 

8 FILENAME 

9 


11 b FULL_ENTRY_SIZE 

12 aa bb dd 

13 ee ff 

14 REL_F_CYCLE_TYPE REL_F_CYCLE 

15 LIFETIME ACCESS_TYPE 

16 EQUIP_TYPE 

17 EQUIP_MNEMONIC 


Figure 3–2. Nonfloating Part of the Return Entry for C Language 

7830 9796–013 3–5



The initial group of items in the file return entry (words 0 – 10) is similar to the file 

identifier structure (see 2.3). The only difference is that the items READ_KEY and 

WRITE_KEY are not included. This part of the entry is always present. The locations of 

all items in this group are defined from the start of the entry. 


Has the same value as the item INTERFACE_LEVEL specified by the calling program 

in the function packet. 


DIRECTORY_ID 

Indicates the name of the directory that contains the file. The only possible values 

(currently) are STD, SHARED, and null. The value null is returned for a file that is 

neither assigned to the run nor cataloged, and for which the Exec has not yet 

established the directory-id. 


QUALIFIER 

Indicates the qualifier for the file. 


FILENAME 

Indicates the basic (external) name of the file. 


F_CYCLE_TYPE 

Indicates if F_CYCLE contains an absolute F-cycle value or a relative F-cycle value. 


ABS = 1 

This value is returned for all files other than those described under REL. 

REL = 2 

This value is returned only for a temporary file assigned with a relative F-cycle or 

for a file that was identified by means of a relative F-cycle, but that is neither 

assigned to the run nor cataloged. 

3–6 7830 9796–013

F_CYCLE 


Indicates the F-cycle of the file. If F_CYCLE_TYPE = ABS, this item has a value 

between 1 and 999 inclusive. If F_CYCLE_TYPE = REL, this item has a value 

between -31 and 1 inclusive. 


The following group of items (word 11) is used for navigating through the return entries. 

These items are present in every file return entry. These items are defined because the 

entries returned by a single call to this function might not all be of the same length. The 

locations of all items in this group are defined from the start of the entry. 

b = EXTENDED_INFO_PRESENT 

Indicates if the remaining items in the nonfloating part of this structure (words 12 to 

18) are present. This item is TRUE only if the calling program set INFO_DETAIL in 

the function packet to LONG or COMPLETE. 


FULL_ENTRY_SIZE 

Indicates the word size of this entire file return entry. 


The following group of items (words 12 and 13) gives the offsets to the nonfixed 

(floating) parts of the entry. These items are present only if EXTENDED_INFO_PRESENT 

= TRUE. If this group of items is present, it is at a fixed location in the entry; all item 

locations are defined from the start of the entry. 

All offset values in this group are given in terms of words from the start of the entry. If 

the offset to any part is zero, that part does not exist in the entry either because it is not 

applicable to the file described by this entry, or because the calling program has not 

requested it. 

aa = CAT_INFO_OFFSET 

Indicates the word offset from the start of the entry to the cataloged-file part of the 

entry. 


bb = SECURITY_INFO_OFFSET 

Indicates the word offset from the start of the entry to the security part of the entry. 


7830 9796–013 3–7


dd = VOL_INFO_OFFSET 

Indicates the word offset from the start of the entry to the volume-information part 

of the entry. 


ee = RUN_ASG_INFO_OFFSET 

Indicates the word offset from the start of the entry to the run-assignment part of 

the entry. 


ff = MEDIUM_INFO_OFFSET 

Indicates the word offset from the start of the entry to the medium-specific part of 

the entry. 


The following group of items (words 14 to 18) gives information applicable to all types of 

files. These items are present only if EXTENDED_INFO_PRESENT = TRUE. For this 

group of items, all item locations are defined from the start of the entry. 

REL_F_CYCLE_TYPE 

Indicates if REL_F_CYCLE contains a relative F-cycle value or no F-cycle value. 



Indicates that the file has no relative F-cycle. These cases include cataloged files 

in the to-be-deleted or the to-be-cataloged states, and temporary files assigned 

with an absolute F-cycle. 

REL = 2 

REL_F_CYCLE 

Indicates that the file has a relative F-cycle, and that its value is contained in 

REL_F_CYCLE. 

Indicates the relative F-cycle of the file, if REL_F_CYCLE_TYPE = REL. Otherwise, it 

contains zero. 


3–8 7830 9796–013

LIFETIME 

Indicates if the file is cataloged or temporary. 


NONE = 0 


Indicates that the file is neither cataloged nor assigned to the run. PCFP returns 

this value if the file identifier that the calling program supplied refers to a file that 

does not exist. 

CATALOGED = 1 

Indicates that the file is cataloged. 

TEMPORARY = 2 

ACCESS_TYPE 

Indicates that the file is temporary. 

Indicates if the file is a random-access file or a sequential-access file. 


NONE = 0 

Indicates that the file is neither cataloged nor assigned to the run. 

RAF = 1 

Indicates that the file is a random-access file. (All mass storage files are 

random-access files.) 

SAF = 2 

Indicates that the file is a sequential-access file. (All tape files are 

sequential-access files.) 

7830 9796–013 3–9


EQUIP_TYPE 

Indicates the general equipment type for the file. 

Data Type: value list 

NONE = 0 

Indicates the file is neither cataloged nor assigned to the run. 

MASS_STORAGE = 1 

Indicates the equipment is mass storage. 

TAPE = 2 

Indicates the equipment is tape. 

MISCELLANEOUS = 99 

Indicates that the equipment is an arbitrary device, communications line, or any 

other equipment falling outside the earlier categories. 

EQUIP_MNEMONIC 

Indicates the mnemonic of the specific equipment type for the file. PCFP returns a 

value for this item only under the following two conditions: 

• EQUIP_TYPE does not equal NONE 

• The calling program set either INFO_DETAIL = COMPLETE or 

RTN_EQUIP_MNEMONIC = TRUE in the function packet 

In instances where PCFP is unable to assign the file to determine its equipment 

mnemonic, PCFP fills this item with all slash characters ( / ). 


3–10 7830 9796–013

3.1.4.2. Cataloged File Part 


The following group of items is present only for cataloged files, and only if the calling 

program has requested detailed information on the file by setting INFO_DETAIL = LONG 

or COMPLETE in the function packet. The location of this group of items varies within 

the entry, and is given by CAT_INFO_OFFSET. If CAT_INFO_OFFSET is zero, this group 

of items is not present. The locations of all items in this group are defined relative to the 

start of the group. See Figure 3–3. 

0 

1 PROJECT_ID 

2 

3 

4 ACCOUNT_ID 

5 

6 ASG_MNEMONIC 


8 a b c d j k l m n 

9 ASG_STATE PRIVACY 

10 aa bb cc 

11 HIGHEST_F_CYCLE 

12 NUM_ASGS SITE_INFO 

13 CAT_DATE_TIME 

14 

15 LAST_REF_DATE_TIME 

16 

Figure 3–3. Cataloged File Part of the Return Entry for C Language 


PROJECT_ID 

Indicates the project identifier for the file. This item contains all slash characters ( / ) 

if the calling program is not privileged to see this item. 


ACCOUNT_ID 

Indicates the account identifier for the file. This item contains all slash characters ( / ) 

if the calling program is not privileged to see this item. 


7830 9796–013 3–11


ASG_MNEMONIC 

Indicates the type mnemonic that was specified when the file was created (with 

@CAT, @ASG,C or @ASG,U). 


a = DIRECTORY_DISABLED 

Indicates if the file is disabled due to directory error. 


b = WRITE_DISABLED 

Indicates if the file is disabled because it was write-enabled and assigned to a run at 

the time of a system stop. 


c = BACKUP_DISABLED 

Indicates if the file is disabled due to inaccessible backup. 


d = CACHE_DISABLED 

Indicates if the file is disabled because it might contain noncurrent data due to cache 

drain failure. 


j = GUARDED 

Indicates that the file was cataloged with the G option, which means that privileged 

runs cannot bypass protection keys. 


k = READ_ONLY 

Indicates that the file has a global restriction preventing it from being updated. 


l = WRITE_ONLY 

Indicates that the file has a global restriction preventing it from being read. 


3–12 7830 9796–013

m = DELETED 


Indicates that the file is marked for deletion. (The deletion occurs after all runs that 

have the file assigned free it.) 


n = SYMMED 

Indicates if the file is on a symbiont queue. 


ASG_STATE 

Indicates whether the file is currently assigned to any run, and if so, the type of the 

assignment. 


NONE = 0 

NON_EXCLUSIVE = 1 

EXCLUSIVE = 2 

TO_BE_CATALOGED = 3 

PRIVACY 

Indicates the privacy status for the file. 


PRIVATE = 1 

SEMIPRIVATE = 2 

PUBLIC = 3 

aa = MAX_F_CYCLES 

Indicates the maximum number of files that can be in the same F-cycle series as this 

file. 

Data Type: unsigned integer range (1 – 32) 

bb = F_CYCLE_COUNT 

Indicates the number of files currently in the same F-cycle series as this file. 


7830 9796–013 3–13


cc = F_CYCLE_RANGE 

Indicates the range of absolute F-cycles of files in the same F-cycle series as this file 

(highest absolute F-cycle minus lowest absolute F-cycle plus 1). 


HIGHEST_F_CYCLE 

This is the highest absolute F-cycle of the files in the same F-cycle series as this file. 


NUM_ASGS 

Indicates the number of times the file was assigned by any run since it was 

cataloged. 


SITE_INFO 

Indicates the value of the site information field in the master file directory entry for 

the file. (Use this information field in any manner you choose.) 


CAT_DATE_TIME 

Indicates the date and time the file was cataloged. 

Data Type: date-time 

LAST_REF_DATE_TIME 

Indicates the date and time the file was most recently assigned or freed (by any run). 


3–14 7830 9796–013

3.1.4.3. Mass Storage Part 


The following group of items is present only for mass storage files, and only if the calling 

program has requested detailed information on the file by setting INFO_DETAIL = LONG 

or COMPLETE in the function packet. The location of this group of items varies within 

the entry, and is given by MEDIUM_INFO_OFFSET. If MEDIUM_INFO_OFFSET is zero, 

this group of items is not present. The locations of all items in this group are defined 

relative to the start of the group. See Figure 3–4. 

0 a b c d e f g h i j LDAT_INDEX 

1 ADDRESS_SIZE GRANULE_SIZE 

2 INIT_SIZE 

3 MAX_SIZE 

4 CURRENT_SIZE 

5 HIGHEST_WORD_ASGD 

6 HIGHEST_WORD_WRITTEN 

7 QUOTA_GROUP_SIZE (1) 








Figure 3–4. Mass Storage Part of the Return Entry for C Language 


a = ROLLOUT_PROHIBITED 

Indicates that the file was cataloged with the V option, which means that a roll-out 

cannot unload it. (The file can, however, be unloaded explicitly.) It is always FALSE 

for temporary files. 


b = BACKED_UP 

Indicates that the file is currently backed up. It is always FALSE for temporary files. 


7830 9796–013 3–15


c = UNLOADED 

Indicates that the file is currently unloaded. It is always FALSE for temporary files. 


d = STORE_THROUGH 

Indicates that the file was cataloged with the S option, which means that its data 

must be written directly on nonvolatile mass storage. It is always FALSE for 

temporary files. 


e = CHECKPOINTED 

Indicates that the file was cataloged with the B option, indicating that it is saved and 

reloaded as part of any full Checkpoint or Restart. It is always FALSE for temporary 

files. 


f = REMOVABLE_DISK 

Indicates that the file resides on removable-disk mass storage. 


g = DEVICE_PLACEMENT 

Indicates that the file was created using device placement. 


h = CONTROL_UNIT_PLACEMENT 

Indicates that the file was created using control unit placement. 


i = LOGICAL_PLACEMENT 

Indicates that the file was created using logical placement, versus absolute 

placement. 


j = MULTIPLE_DEVICES 

Indicates that the file is spread across more than one mass storage device. 


3–16 7830 9796–013

LDAT_INDEX 


Indicates the logical device address table (LDAT) index of the mass storage device 

that was initially selected for the file. 


ADDRESS_SIZE 

Indicates the size in words of the smallest unit of the file that can be addressed by 

I/O. Possible values are 1 (word-addressable files) and 28 (sector-addressable files). 


GRANULE_SIZE 

Indicates the size in words of the mass storage granules allocated to the file. 

Possible values are 1792 (64 * 28-track granularity) and 114688 

(64 * 64 * 28-position granularity). 


INIT_SIZE 

Indicates the size of the initial reserve of the file in words. 


MAX_SIZE 

Indicates the maximum size of the file in words. 


CURRENT_SIZE 

Indicates the number of words of mass storage currently allocated to the file. A 

value of zero implies no mass storage has been allocated to the file. 


HIGHEST_WORD_ASSIGNED 

Indicates the location of the highest word of mass storage currently assigned 

(allocated) to the file. Words in the file are numbered starting at 0. A value of zero 

implies no mass storage has been allocated to the file (since mass storage is always 

allocated in multiples of a granule). To determine the highest granule assigned to 

the file, divide this value by GRANULE_SIZE and discard the remainder. 


7830 9796–013 3–17


HIGHEST_WORD_WRITTEN 

Indicates the number of the highest word of mass storage currently written in the 

file. Words in the file are numbered starting at 0. (Note that for cataloged files, all 

words in a track are considered written if at least one word in the track was written. 

Thus for a cataloged file, this value is always the last word of a track.) To determine 

the highest track written in the file, divide this value by the size of a track (1792 

words) and discard the remainder. 


QUOTA_GROUP_SIZE array (1:8) 

3.1.4.4. Tape Part 

For each of the mass-storage quota groups 1 – 8, the Nth element of this array gives 

the number of words currently allocated to the file in the Nth quota group. The sum 

of the values in this array equals the value in CURRENT_SIZE. 


The following group of items is present only for tape sequential-access files, and only if 

the calling program has requested detailed information on the file by setting 

INFO_DETAIL = LONG or COMPLETE in the function packet. The location of this group 

of items varies within the entry, and is given by MEDIUM_INFO_OFFSET. If 

MEDIUM_INFO_OFFSET is zero, this group of items is not present. The locations of all 

items in this group are defined relative to the start of the group. See Figure 3–5. 

Note: Figure 3–5 shows the new format long form of information that is returned when 

INTERFACE_LEVEL has a value of at least FP_INTERFACE_LEVEL_2. A new return 

information Tape Part definition must be used when specifying the new interface level. 

For C users, the new definition name is fp_rtn_file_info_tape_2_type. If you modify an 

existing ACQ_FILE_INFO or ACQ_FILE_LIST function to use an INTERFACE_LEVEL 

value of FP_INTERFACE_LEVEL_2, you must also modify the return information Tape 

Part definition to use the new definition name. For compatibility, the previous definition 

name is unchanged and describes the interface level 1 Tape Part. The format of the 

interface level 1 Tape Part is described in comments in the previous definition. 

3–18 7830 9796–013


0 a b c d aa bb 

1 TAPE_CLASS RECORDING_DENSITY 

2 cc ee ff 

3 TRANSLATION_PROCESSOR_MNEMONIC 

4 TRANSLATION_PROCESSOR_ 

MNEMONIC 

5 TRANSLATION_TAPE_MNEMONIC 

6 TRANSLATION_TAPE_MNEMONIC VOLUME_INDEX 

7 LOGICAL_FILE_POSITION 

8 WRITEPROTECT_INDICATOR e 

9 TAPE_UNIT_1_ID 




Figure 3–5. Tape Part of the Return Entry for C Language 


a = LABELED 

Indicates that the tape file is labeled. 


b = PARITY 

Indicates that the tape file is recorded with odd or even parity. This item can be 

EVEN only when TAPE_CLASS = SEVEN_TRACK. 


ODD = 0 

EVEN = 1 

c = DATA_CONVERTER 

If TRUE, indicates that three 8-bit bytes convert to or from four 6-bit tape characters 

when the tape file is written or read. This item can be TRUE only if TAPE_CLASS = 

SEVEN_TRACK. 


7830 9796–013 3–19


d = BUFFERED 

Indicates that data buffering applies to the tape file. This item can be TRUE only if 

TAPE_CLASS = HIC. 


aa = BLOCK_NUMBERING 

Indicates that block numbering applies to the tape file. The three values correspond 

to the values BLKOFF, BLKON, and BLKOPT that can be specified when a tape file is 

cataloged or assigned. This item can have a value other than BLKOFF only if 

TAPE_CLASS = NINE_TRACK. 


BLKOFF = 0 

BLKON = 1 

BLKOPT = 3 

bb = DATA_COMPRESSION 

Indicates the data compression setting for the tape file. The names of the following 

values correspond to the data compression mnemonics that can be specified when a 

tape file is cataloged or assigned. Data compression values other than CMPOFF can 

be used only when TAPE_CLASS = NINE_TRACK or HIC. 


CMPOFF = 0 Data compression is off. 

CMPON = 1 Data compression is on. 

CMPOPT = 3 Data compression capable unit is required. 

CMP8ON = 4 Eight-bit data compression is on. 

CMP9ON = 5 Nine-bit data compression is on. 

CMPEON = 6 EDRC data compression is on. 

CMEOPT = 7 ERDC data compression capable unit is required. 

CMPLON = 8 LZ1 data compression is on. 

3–20 7830 9796–013

TAPE_CLASS 


Indicates the general class of the tape file. The specific tape type is in item 

EQUIP_MNEMONIC. 


NINE_TRACK = 1 

SEVEN_TRACK = 2 

HIC = 3 HIC refers to half-inch cartridge. 

QIC = 4 QIC refers to quarter-inch cartridge. 

VIRTUAL = 5 A virtual tape is a simulated tape stored in a mass 

storage file and maintained by the Virtual Tape 

Handler (VTH), a Separately Packaged Exec 

Feature (SPEF). 

DVD = 6 A DVD is being processed as a simulated tape. 

RECORDING_DENSITY 

Indicates the recording density for the tape file. 


For all TAPE_CLASS values, the following can be returned: 

UNKNOWN = 0 For TAPE_CLASS = VIRTUAL and DVD, this value indicates 

that density does not apply. For other TAPE_CLASS values, 

this value indicates that density could not be determined. 

For TAPE_CLASS = SEVEN_TRACK, only the following values can be returned: 

L = 1 Density of 200 bits per inch (bpi) 

M = 2 Density of 556 bpi 

H = 3 Density of 800 bpi 

For TAPE_CLASS = NINE_TRACK, only the following values can be returned: 

H = 3 Density of 800 bpi 

V = 4 Density of 1,600 bpi 

S = 5 Density of 6,250 bpi 

7830 9796–013 3–21


For TAPE_CLASS = HIC, only the following values can be returned: 

HICL = 6 Density of 37,871 bpi, 18-track tape 

HICM = 7 Density of 75,742 bpi, 36-track tape 

DLTM = 8 Density of 85,937 bpi, 208-track tape 

HISL = 9 9840 family, low density of 5,090 bpmm (bits per millimeter), 

288-track tape 

HISM = 10 9940 family, medium density, 288-track tape 

HISM2 = 11 9840 family, medium density, 288-track tape 

HISH = 12 9840 family, high density, 576-track tape 

T10KL = 13 T10000 family, low density,768-track tape 

LTO = 20 LTO family, density unknown 

LTO1 = 21 LTO family, density of 4,880 bpmm, 384-track tape 




Note: For HISM = 10, HISM2 = 11, HISH =12, and T10KL=13, the tape drive 

manufacturer does not provide exact density specifications. 

cc = BUFFERED_WRITE 

Indicates the buffered write mode for the tape file. The names of the following 

values (except DEFAULT) correspond to the tape buffering mnemonics that can be 

specified when a tape file is cataloged or assigned. Buffered write values other than 

DEFAULT and BUFOFF are returned only when TAPE_CLASS = HIC. 

Data type: value-list 

DEFAULT = 0 For TAPE_CLASS other than HIC, buffered write modes are not 

supported. For TAPE_CLASS = HIC, this is a cataloged file and the 

buffered write mode is determined by the Exec configuration 

parameter tape_buffering. 

BUFOFF = 1 All buffered write modes are disabled. 

BUFFON = 2 Buffered write mode is enabled for user data blocks. 

BUFFIL = 3 Buffered write mode is enabled for user data blocks, and for label 

blocks and tape marks written to labeled tapes by the Exec tape 

labeling system. 

BUFTAP = 4 Buffered write mode is enabled for user data blocks, user tape 

marks, and for label blocks and tape marks written to labeled tapes 

by the Exec tape labeling system. 

ee = DATA_TRANSFER_FORMAT 

Indicates the data transfer format for word-to-byte conversion. 


3–22 7830 9796–013

NONE = 0 

QUARTER_WORD = 1 

SIX_BIT = 2 

EIGHT_BIT = 3 

ff = NOISE_VALUE 


Indicates the noise value for the tape file. A value of zero means that the system 

standard noise value is in use for this tape file. 


TRANSLATION_PROCESSOR_MNEMONIC 

Indicates the mnemonic of the processor type for processor tape translation. 


TRANSLATION_TAPE_MNEMONIC 

Indicates the mnemonic of the tape type for processor tape translation. 


The following items are applicable only if the tape file is assigned to the run of the calling 

program. PCFP assigns values to these items only if the file is assigned to the run of the 

calling program, and the calling program has requested the return of run-assignment 

information (by setting either RTN_RUN_ASG_INFO = TRUE or INFO_DETAIL = 

COMPLETE in the function packet). 

VOLUME_INDEX 

Indicates the index of the volume at which the tape file is currently positioned. If no 

volume is currently mounted for the file, this value is zero. 


LOGICAL_FILE_POSITION 

Indicates the position on the current volume of the logical file at which the tape file is 

currently positioned. 


WRITEPROTECT_INDICATOR 

Indicates whether WRITEPROTECT (NORING), WRITEENABLE (RING), or neither 

was specified when the file was assigned to the run of the calling program. 


7830 9796–013 3–23



WRITEPROTECT = 1 

WRITEENABLE = 2 

e = LOCATE_BLOCK 

Indicates if the tape has been positioned using the Locate Block (LBLK$) I/O 

function, issued either by the PCFP MOVE_SAF function or by a caller application. If 

TRUE, the LOGICAL_FILE_POSITION is unknown and is set to zero. 


TAPE_UNIT_1_ID 

Indicates the identifier of the first (perhaps only) tape unit assigned to the file. 


TAPE_UNIT_2_ID 

Indicates the identifier of the second tape unit assigned to the file. If the file has 

only one unit assigned, this item contains null. 


3.1.4.5. Security Part 

The following group of items is present only for cataloged files, and only if the calling 

program has requested this information on the file either by setting 

RTN_SECURITY_INFO = TRUE and INFO_DETAIL = LONG or by setting INFO_DETAIL = 

COMPLETE in the function packet. The location of this group of items varies within the 

entry, and is given by SECURITY_INFO_OFFSET. If SECURITY_INFO_OFFSET is zero, 

this group of items is not present. The locations of all items in this group are defined 

relative to the start of the group. See Figure 3–6. 

0 READ_KEY 

1 READ_KEY 

2 WRITE_KEY 

3 WRITE_KEY 

4 ACR_NAME 

5 ACR_NAME 

6 

7 FILE_OWNER_USER_ID 

8 

9 CLEARANCE_LEVEL 

Figure 3–6. Security Part of Return Entry for C Language 

3–24 7830 9796–013


READ_KEY 


Indicates the read key used when assigning the file. This item contains all nulls if 

the file has no read key. This item contains all slash characters ( / ) if the file has a 

read key and the calling program is not privileged to see it. 


WRITE_KEY 

Indicates the write key to be used when assigning the file. This item contains all 

nulls if the file has no write key. This item contains all slash characters ( / ) if the file 

has a write key and the calling program is not privileged to see it. 


ACR_NAME 

Indicates the name of the access control record attached to the file. This item has a 

value other than null only when PRIVACY = SEMIPRIVATE. 


FILE_OWNER_USER_ID 

Indicates the user-id of the owner of the file. 


CLEARANCE_LEVEL 

3.1.4.6. Volume Part 

Indicates the security clearance level for the file. 


The following group of items is present only for tape files, and for cataloged mass 

storage files that reside on removable disk (those for which REMOVABLE_DISK = 

TRUE). Also, it is present only if the calling program has requested this information on 

the file either by setting RTN_VOL_INFO = TRUE and INFO_DETAIL = LONG or by 

setting INFO_DETAIL = COMPLETE in the function packet. The location of this group of 

items varies within the entry, and is given by VOL_INFO_OFFSET. If 

VOL_INFO_OFFSET is zero, this group of items is not present. The locations of all items 

in this group are defined relative to the start of the group. See Figure 3–7. 

7830 9796–013 3–25


0 X_WDS NUM_VOLS 

1 VOL_ID 

2 VOL_ID 

.. … 

2n-1 VOL_ID 

2n+1 

2n VOL_ID 

2n+2 TAPE_POOL_NAME 

2n+3 

Figure 3–7. Volume Part of the Return Entry for C Language 


X_WDS 

Indicates the number of words in the volume section beyond those words occupied 

by VOL_ID items. These words contain a tape pool name if one exists for this file. If 

no tape pool name exists, this item, X_WDS, will contain a zero. 


NUM_VOLS 

Indicates the number of volumes composing the tape file or the number of 

removable packs on which the mass storage file can reside. 


VOL_ID array (1:n) 

For a tape file, this item gives the proper order of the identifiers of the volumes 

(reels or cartridges) composing the tape file. For a mass storage file assigned to 

removable packs, this item gives the identifiers of the packs on which the mass 

storage file can reside; in this case, the order is undefined. This array contains 

NUM_VOLS entries. 


TAPE_POOL_NAME 

When a Cartridge Tape Library (CTL) is configured and these volumes belong to a 

tape pool within CTL, this item will contain the name of the tape pool. 


3–26 7830 9796–013

3.1.4.7. Run Assignment Part 


The following group of items is present only if the calling program has requested this 

information either by setting RTN_RUN_ASG_INFO = TRUE and INFO_DETAIL = LONG 

or by setting INFO_DETAIL = COMPLETE in the function packet. The location of this 

group of items varies within the entry, and is given by RUN_ASG_INFO_OFFSET. If 

RUN_ASG_INFO_OFFSET is zero, this group of items is not present. The locations of all 

items in this group are defined relative to the start of the group. See Figure 3–8. 

0 a b c NUM_USE_NAMES 

1 d d d d d d d d d d d d d d d d d d d d d d d d d d 

2 

3 USE_NAME 

4 

3n-1 

3n+1 

.. ... 

3n USE_NAME 

Figure 3–8. Run Assignment Part of the Return Entry for C Language 


a = ASGD_TO_RUN 

Indicates that the file is currently assigned to the run of the calling program. 


b = READABLE 

Indicates that the file, as it is currently assigned to the run of the calling program, can 

be read by that run. This item is always FALSE if ASGD_TO_RUN = FALSE. 


c = WRITEABLE 

Indicates that the file, as it is currently assigned to the run of the calling program, can 

be written to or updated by that run. This item is always FALSE if ASGD_TO_RUN = 

FALSE. 


7830 9796–013 3–27


NUM_USE_NAMES 

Indicates the number of internal (use) names the run of the calling program has given 

to this file. 


d = ASG_OPTIONS array (1:26) 

Indicates the options used when the file was assigned to the run of the calling 

program. All items in this array are FALSE (zero) if ASGD_TO_RUN = FALSE. 


USE_NAME array (1:n) 

Indicates the internal (use) name given by the run of the calling program to this file. 

This array contains NUM_USE_NAMES entries. The array is not present if the file 

does not have internal names. 


3.1.5. Return Information (COBOL and FORTRAN) 

The structure of the return information parameter is defined in element FP$RTN$FILE. 

Upon successful completion of this function, PCFP creates one return entry. The 

contents of this return entry vary depending on what the calling program has requested 

in the function packet, and on the type of file the entry describes. Also, the structure of 

the return entry varies, depending on the language in which the calling program is 

written. 

For COBOL and FORTRAN programs, this function produces a fixed-sized entry 

described in 3.1.5.1 and 3.1.5.2. 

If the size of the return area specified by RTN_AREA_SIZE is not sufficient to contain the 

complete return entry, error code fp_err_small_return_area (decimal 1062) is returned in 

the function packet ERROR_CODE item. No information is returned, and the function 

packet RTN_ENTRY_SIZE and NUM_ENTRIES_IN_RTN_AREA items contain zeroes. 

Note: Figure 3–11 shows the new format long form of information that is returned 

when INTERFACE_LEVEL has a value of at least FP_INTERFACE_LEVEL_2. A new long 

form return information definition must be used when specifying the new interface level. 

• For COBOL users, the definition name is FP-RTN-FILE-INFO-LONG-2. 

• For FORTRAN users, the definition name is FP$RTN$FILL2. 

If you modify an existing ACQ_FILE_INFO or ACQ_FILE_LIST function to use an 

INTERFACE_LEVEL value of FP_INTERFACE_LEVEL_2, you must also modify the long 

form return information definition to use the new definition name. For compatibility, the 

previous definition names are unchanged and describe the interface level 1 return 

3–28 7830 9796–013


information. The format of the interface level 1 return information is described in the 

previous definition. 

3.1.5.1. Short Form Return Information (COBOL and FORTRAN) 

PCFP returns one of two fixed-size forms of the return entry described in 3.1.4 when 

ACQ_FILE_INFO is called from a COBOL or FORTRAN program. The short form is 

returned when the calling program sets INFO_DETAIL = SHORT in the function packet. 

Figure 3–9 shows this short form. 

0 




4 

5 QUALIFIER 

6 

7 

8 FILENAME 

9 


Figure 3–9. Mass Storage Part of the Return Entry for COBOL and 

FORTRAN Short Form 


Item descriptions are the same as in 3.1.4. 

7830 9796–013 3–29


3.1.5.2. Long Form Return Information (COBOL and FORTRAN) 

The long form is returned where the calling program sets INFO_DETAIL = LONG or 

COMPLETE in the function packet. If a particular substructure does not apply to a file, or 

the calling program has not requested return of the information in that substructure, 

PCFP fills the entire substructure with zeros. Figure 3–10 shows the long form. 

When this is a mass storage file, Figure 3–10 shows the contents of words 0 through 84 

of the long form. When this is a tape file, Figure 3–11 shows the contents of words 34 

through 48 of the long form. 

0 




4 

5 QUALIFIER 

6 

7 

8 FILENAME 

9 


11 a b c d e f h 

12 REL_F_CYCLE_TYPE REL_F_CYCLE 

13 LIFETIME ACCESS_TYPE 

14 EQUIP_TYPE 



17 

18 PROJECT_ID 

19 

20 

21 ACCOUNT_ID 

22 



25 a b c d j k l m n 

Figure 3–10. Long Form Return Entry for Mass Storage File for COBOL 

and FORTRAN (cont.) 

3–30 7830 9796–013


26 ASG_STATE PRIVACY 

27 aa bb cc 

28 HIGHEST_F_CYCLE 

29 NUM_ASGS SITE_INFO 

30 CAT_DATE_TIME 

31 

32 LAST_REF_DATE_TIME 

33 

34 a b c d e f g h i j LDAT_INDEX 

35 ADDRESS_SIZE GRANULE_SIZE 

36 INIT_SIZE 

37 MAX_SIZE 

38 CURRENT_SIZE 

39 HIGHEST_WORD_ASGD 










49 READ_KEY 

50 READ_KEY 

51 WRITE_KEY 

52 WRITE_KEY 

53 ACR_NAME 

54 ACR_NAME 

Figure 3-10. Long Form Return Entry for Mass Storage File for COBOL 

and FORTRAN (cont.) 

7830 9796–013 3–31


55 


57 

58 CLEARANCE_LEVEL 

59 X_WDS NUM_VOLS 

60 VOL_ID (1) 

61 VOL_ID (1) 

62 VOL_ID (2) 

63 VOL_ID (2) 

64 VOL_ID (3) 

65 VOL_ID (3) 

66 

67 TAPE_POOL_NAME 

68 

69 

70 

71 

72 

73 

74 a b c NUM_USE_NAMES 

75 d d d d d d d d d d D d d d d d d d d d d d d d d d 

76 

77 USE_NAME (1) 

78 

79 


81 

82 


84 

Figure 3–10. Long Form Return Entry for Mass Storage File for COBOL 

and FORTRAN 

3–32 7830 9796–013


34 a b c d aa bb 

35 TAPE_CLASS RECORDING_DENSITY 

36 cc ee ff 

37 TRANSLATION_PROCESSOR_MNEMONIC 

38 TRANSLATION_PROCESSOR_ 

MNEMONIC 

39 TRANSLATION_TAPE_MNEMONIC 

40 TRANSLATION_TAPE_MNEMONIC VOLUME_INDEX 


42 WRITEPROTECT_INDICATOR e 





47 

48 

Figure 3–11. Long Form Tape Part of the Return Entry for COBOL and 

FORTRAN 

7830 9796–013 3–33



INTERFACE_LEVEL (word 1) through F_CYCLE (word 10) are the same as the 

corresponding items described in 3.1.4.1. These items are always present. 

Word 11 

a = EXTENDED_INFO_PRESENT 

Indicates whether the items REL_F_CYCLE_TYPE through EQUIP_MNEMONIC 

(words 12 – 16) contain valid values. These items are defined in 3.1.4.1. 


b = CAT_INFO_PRESENT 

Indicates whether the items PROJECT_ID through LAST_REF_DATE_TIME (words 

17 – 33) that describe a cataloged file contain valid values. These items are defined 

in 3.1.4.2. 


c = MASS_STORAGE_INFO_PRESENT 

Indicates whether the items that describe a mass storage file 

(ROLLOUT_PROHIBITED through QUOTA_GROUP_SIZE, words 34 – 48 in 

Figure 3–10) contain valid values. These items are defined in 3.1.4.3. 


d = TAPE_INFO_PRESENT 

Indicates whether the items that describe a tape file (LABELED through 

TAPE_UNIT_2_ID, words 34 – 48 in Figure 3–11) contain valid values. These items 

are defined in 3.1.4.4. Note that these items overlay those that describe a mass 

storage file, and that MASS_STORAGE_INFO_PRESENT and TAPE_INFO_PRESENT 

cannot both be TRUE. 


e = SECURITY_INFO_PRESENT 

Indicates whether the items READ_KEY through CLEARANCE_LEVEL (words 49 – 

58) that describe the security characteristics of the file contain valid values. These 

items are defined in 3.1.4.5. 


3–34 7830 9796–013

f = VOL_INFO_PRESENT 


Indicates whether the items NUM_VOLS through VOL_ID (words 59 – 65) that 

describe the volumes of the file contain valid values. These items are defined in 

3.1.4.6. Note that if the file has more than three volumes, only the identifiers of the 

first three are returned, although NUM_VOLS contains the total number for the file. 

Data Types: condition 

h = RUN_ASG_INFO_PRESENT 

Indicates whether the items ASGD_TO_RUN through USE_NAME (words 74 – 84) 

that describe how the file is assigned to the run of the calling program contain valid 

values. These items are defined in 3.1.4.7. Note that if the file has more than three 

internal names attached, only three are returned, although NUM_USE_NAMES 

contains the total number for the file. 

Data Types: condition 

Words 12 – 16 See the description of words 14 – 18 in 3.1.4.1. 

Words 17 – 33 See 3.1.4.2. 

Words 34 – 48 If this is a mass storage file, see Figure 3–10 and 3.1.4.3. 

Words 49 – 58 See 3.1.4.5. 

Words 59 – 68 See 3.1.4.6. 

If this is a tape file, see Figure 3–11 and 3.1.4.4. 

Words 69 – 73 Unused and always contain zero. 

Words 74 – 84 See 3.1.4.7. 

3.1.6. Work Area 

ACQ_FILE_INFO requires 1,000 words for its work area. There is one special situation in 

which 1,000 words is insufficient for this function. If the file being examined has more 

than 160 internal (@USE) names attached, this function requires an additional 5 words of 

work area for each internal name in excess of 160. 

The total of WORK_AREA_SIZE and RTN_AREA_SIZE should not exceed approximately 

205,000 words. This is the approximate maximum size that can be specified for this 

function, where the minimum relative address is MIN_DATA_ADDR and the maximum 

relative address is MAX_DATA_ADDR_WITH_PCT, as contained in the copy/include 

element FP$DEFS. 

7830 9796–013 3–35


3.2. Acquire File List (ACQ_FILE_LIST) 

ACQ_FILE_LIST acquires directory information about one or more files that meet 

conditions specified by the calling program. At a minimum, this function returns to the 

calling program the external identifiers of all files that are selected (with the exception of 

the read and write keys). The file identifiers are returned in a form usable as input to 

other functions that operate on files. Thus, if a program must perform an operation on all 

files that meet some conditions, it can call this function first to obtain the identifiers of all 

the files meeting the conditions, then repeatedly call the appropriate function to perform 

the operation on each file identifier returned. 

The calling program can select files based on a number of attributes. The attributes are 

described in 3.2.2. Each attribute for which a value is supplied further restricts the set of 

files that is selected. The calling program may supply values for as few or as many of 

these attributes as it requires. 

When this function selects a list of files, it assumes no default selection criteria. Unless 

the calling program explicitly specifies a particular attribute, this function assumes that all 

values of that attribute qualify. This means, for example, that the calling program must 

specify a directory-id if it must limit the search to a specific directory. 

This function returns all the same information as that returned by ACQ_FILE_INFO. See 

3.1.4 and 3.1.5 for the full description of this information. As with the ACQ_FILE_INFO 

function, this function provides a means for returning only selected subsets of the full 

set of attributes to the calling program. The composition of these subsets is given in 

3.1.4 and 3.1.5. Also, as with ACQ_FILE_INFO, the operating system may mask certain 

of the returned attributes for security purposes. 


The ACQ_FILE_LIST function has the following parameters, each of which is described 



• Return Information 

• Work Area 

3–36 7830 9796–013



The structure of the ACQ_FILE_LIST function packet is defined in element 

FP$ACQFILLST. See Figure 3–12. 

GENERIC PART 


0 INFO_DETAIL b c d e 

1 SEARCH_SET LIFETIME 

2 

3 



6 

7 QUALIFIER 

8 

9 

10 FILENAME 

11 

12 PACK_ID 

13 PACK_ID 

14 MIN_F_CYCLE_TYPE MIN_F_CYCLE 

15 MAX_F_CYCLE_TYPE MAX_F_CYCLE 

16 

17 PROJECT_ID 

18 

19 

20 ACCOUNT-ID 

21 

Figure 3–12. ACQ_FILE_LIST Function Packet Items (cont.) 

22 ACR_NAME 

7830 9796–013 3–37


23 ACR_NAME 

24 


26 

27 MIN_CLEARANCE_LEVEL 

28 MAX_CLEARANCE_LEVEL 

29 MIN_CAT_DATE_TIME 

30 

31 MAX_CAT_DATE_TIME 

32 

33 MIN_LAST_REF_DATE_TIME 

34 

35 MAX_LAST_REF_DATE_TIME 

36 

37 

38 

39 

40 

41 EQUIP_TYPE f SITE_INFO 


43 

44 

45 

46 



Figure 3–12. ACQ_FILE_LIST Function Packet Items 



FP_INTERFACE_LEVEL_2. If this item is set to FP_INTERFACE_LEVEL_1, the long 

form return information has a format different than that described in 3.1.4 and 3.1.5. 


INFO_DETAIL 

3–38 7830 9796–013


For each individual file selected by this function, indicates what subset of information 

PCFP returns. 


SHORT = 0 

Indicates that PCFP returns only the file identifier for each file. 

LONG = 1 

Indicates that PCFP returns information beyond the file identifier, including any 

subsets of information indicated by the items RTN_VOL_INFO, 

RTN_SECURITY_INFO, RTN_RUN_ASG_INFO and RTN_EQUIP_MNEMONIC. 

(The description of the return entry in 3.1.4 indicates the items included.) 

COMPLETE = 2 

Indicates that PCFP returns all information obtainable through this function. 

When the calling program sets INFO_DETAIL to COMPLETE, the calling program 

receives the same information it would receive by setting INFO_DETAIL to 

LONG, and RTN_VOL_INFO, RTN_SECURITY_INFO, RTN_RUN_ASG_INFO, 

RTN_EQUIP_MNEMONIC all to TRUE. 

b = RTN_VOL_INFO 

Indicates whether the function returns volume information for each file selected by 

the function that has volume information. (Only tape files and mass storage files on 

removable disk can have volume information.) This item is ignored unless 

INFO_DETAIL = LONG. 


c = RTN_SECURITY_INFO 

Indicates whether the function returns security information for each cataloged file 

selected by the function that has security information. This item is ignored unless 

INFO_DETAIL = LONG. 


d = RTN_RUN_ASG_INFO 

Indicates whether the function returns run-assignment information for each file 

selected by the function. This item is ignored unless INFO_DETAIL = LONG. 


7830 9796–013 3–39


e = RTN_EQUIP_MNEMONIC 

Indicates whether the function returns the equipment mnemonic for each file 

selected by the function. This item is ignored unless INFO_DETAIL = LONG. 


SEARCH_SET 

Indicates which basic set of files PCFP considers for selection by this function. 


ASGD_TO_RUN = 1 

This value indicates that the files to be considered are those assigned to the run 

of the calling program. 

KNOWN_TO_RUN = 2 

This value indicates that the files to be considered are those assigned to the run 

of the calling program and to which an internal (@USE) name has been attached 

by that run. 

CATALOG_DIRECTORY = 3 

LIFETIME 

This value indicates that the files to be considered are those contained within 

the cataloged file directory(s) indicated by DIRECTORY_ID. When the calling 

program specifies this value, it must also specify both QUALIFIER and 

FILENAME and must not include masking characters in these values. 

Indicates whether the files to be selected must be cataloged, temporary, or either. 


NO_CONSTRAINT = 0 

CATALOGED = 1 

TEMPORARY = 2 

Note that if LIFETIME = TEMPORARY and SEARCH_SET = CATALOG_DIRECTORY, 

no files can be selected by the function. 

DIRECTORY_ID 

Indicates the name of the directory from which files are to be selected. The only 

legal values (currently) are STD and SHARED; a null value indicates that this function 

is to select files without regard to directory-id. 


3–40 7830 9796–013

QUALIFIER 


Indicates the qualifier or pattern of the qualifier of the files this function selects. 

Unless the calling program set SEARCH_SET = CATALOG_DIRECTORY, the value 

the calling program supplies for this item may contain the question mark ( ? ) and the 

asterisk ( * ) wild-card characters as described in 2.6. A null value indicates that this 

function selects files without regard to qualifier. 


FILENAME 

Indicates the name or pattern of the name of the files this function selects. This 

value is compared only against the intrinsic (external) file name; it is never compared 

to an internal name that the run of the calling program might have attached. Unless 

the calling program set SEARCH_SET = CATALOG_DIRECTORY, the value the 

calling program supplies for this item may contain the question mark ( ? ) and the 

asterisk ( * ) wild-card characters as described in 2.6. A null value indicates that this 

function selects files without regard to file name. 


PACK_ID 

Indicates the removable pack from which the files are selected. A null value 

indicates that this function selects files without regard to the removable pack on 

which they reside. 


MIN_F_CYCLE_TYPE 

Indicates whether MIN_F_CYCLE contains an absolute F-cycle value, a relative 

F-cycle value, or no F-cycle value. 



Indicates that this function selects files without regard to a minimum F-cycle. 

ABS = 1 

Indicates that this function limits the files it selects to those with an absolute 

F-cycle greater than or equal to MIN_F_CYCLE. Files with no absolute F-cycle 

are not selected. 

REL = 2 

Indicates that this function limits the files it selects to those with a relative 

F-cycle greater than or equal to MIN_F_CYCLE. Files with no relative F-cycle are 

not selected. 

7830 9796–013 3–41


MIN_F_CYCLE 

Indicates the minimum F-cycle of the files this function selects. (Files with a lower 

F-cycle are not selected.) If MIN_F_CYCLE_TYPE = UNSPECIFIED, this item must 

have value 0. If MIN_F_CYCLE_TYPE = ABS, this item must have a value between 1 

and 999 inclusive. If MIN_F_CYCLE_TYPE = REL, this item must have a value 



MAX_F_CYCLE_TYPE 

Indicates whether MAX_F_CYCLE contains an absolute F-cycle value, a relative 

F-cycle value, or no F-cycle value. 


UNSPECIFIED =0 

Indicates that this function selects files without regard to a maximum F-cycle. 

ABS = 1 

Indicates that this function limits the files it selects to those with an absolute 

F-cycle less than or equal to MAX_F_CYCLE. Files with no absolute F-cycle are 

not selected. 

REL = 2 

Indicates that this function limits the files it selects to those with a relative 

F-cycle less than or equal to MAX_F_CYCLE. Files with no relative F-cycle are 

not selected. 

If the calling program set MIN_F_CYCLE_TYPE = REL, it cannot set 

MAX_F_CYCLE_TYPE = ABS, and vice versa. 

MAX_F_CYCLE 

Indicates the maximum F-cycle of the files this function selects. (Files with a higher 

F-cycle are not selected.) If MAX_F_CYCLE_TYPE = UNSPECIFIED, this item must 

have value 0. If MAX_F_CYCLE_TYPE = ABS, this item must have a value between 

1 and 999 inclusive. If MAX_F_CYCLE_TYPE = REL, this item must have a value 



3–42 7830 9796–013

PROJECT_ID 


Indicates the project-id or pattern of project-id of the files this function selects. The 

value the calling program supplies for this item may include the question mark ( ? ) 

and the asterisk ( * ) wild-card characters as described in 2.6. A value of all slashes 

( / ) limits the files selected to those whose project-id the run of the calling program 

is not privileged to see. A null value for this item indicates that this function selects 

files without regard to project-id. 


ACCOUNT_ID 

Indicates the account identifier or pattern of account identifier of the files this 

function selects. The value the calling program supplies for this item may include 

the question mark ( ? ) and the asterisk ( * ) wild-card characters as described in 2.6. 

A value of all slashes ( / ) limits the files selected to those whose account identifier 

the run of the calling program is not privileged to see. A null value for this item 

indicates that this function selects files without regard to account identifier. 


ACR_NAME 

Indicates the name or pattern of the name of the access control record (ACR) 

attached to the files this function selects. The value the calling program supplies for 

this item may include the question mark ( ? ) and the asterisk ( * ) wild-card 

characters as described in 2.6. A null value for this item indicates that this function 

selects files without regard to access control record. 



Indicates the user-id of the owner or pattern of the user-id of the owner of the files 

this function selects. The value the calling program supplies for this item may 

include the question mark ( ? ) and the asterisk ( * ) wild-card characters as described 

in 2.6. A null value for this item indicates that this function selects files without 

regard to owner user-id. 


MIN_CLEARANCE_LEVEL 

Indicates the minimum clearance level for the files this function selects. A value of 

zero indicates that this function selects files without regard to a minimum clearance 

level. 

Data Type: unsigned integer, range (0 – 63) 

7830 9796–013 3–43


MAX_CLEARANCE_LEVEL 

Indicates the maximum clearance level for the files this function selects. A value of 

zero indicates that this function selects the files without regard to a maximum 

clearance level. 

Data Type: unsigned integer, range (0 – 63) 

MIN_CAT_DATE_TIME 

Indicates the earliest date and time at which the files this function selects were 

cataloged. A value of zero indicates that this function selects files without regard to 

a minimum date and time of creation. 


MAX_CAT_DATE_TIME 

Indicates the latest date and time at which the files this function selects were 

cataloged. A value of zero indicates that this function selects files without regard to 

a maximum date and time of creation. 


MIN_LAST_REF_DATE_TIME 

Indicates the earliest date and time at which the files this function selects were 

most recently referenced (assigned). A value of zero indicates that this function 

selects files without regard to a minimum date and time of reference. 


MAX_LAST_REF_DATE_TIME 

Indicates the latest date and time at which the files this function selects were most 

recently referenced. A value of zero indicates that this function selects files without 

regard to a maximum date and time of reference. 


3–44 7830 9796–013

EQUIP_TYPE 


Indicates the general equipment type that the files this function selects must have. 

A value of NONE indicates that this function selects files without regard to 

equipment type. 


NONE = 0 

MASS_STORAGE =1 

TAPE = 2 

MISCELLANEOUS = 99 

The value MISCELLANEOUS refers to arbitrary devices, communications lines, and 

other equipment not covered by the earlier categories. 

f = SELECT_ON_SITE_INFO 

If TRUE, this function selects only files that have site information in the master file 

directory that matches the value the calling program specified in SITE_INFO. (The 

site-information field can be used by a site in any manner it chooses.) 


SITE_INFO 

If SELECT_ON_SITE_INFO = TRUE, this item gives the value of the site information 

that PCFP must match. If SELECT_ON_SITE_INFO = FALSE, this item must contain 

zero. 

Data Type: half word unsigned integer 

NUM_SELECTED 

Indicates how many files this function selected. 


7830 9796–013 3–45


3.2.3. Return Information 

The return information parameter produces one return entry for each file it selects. The 

format of this return entry is identical to that produced by the function ACQ_FILE_INFO, 

and is described in 3.1.4 for calling programs written in C and in 3.1.5 for calling 

programs written in COBOL and FORTRAN. 

Note: Subsections 3.1.4.4 and 3.1.5 describe the new format long form information 

that is returned when INTERFACE_LEVEL has a value of at least 

FP_INTERFACE_LEVEL_2. A new long form return information definition must be used 

when specifying the new interface level. 

• For C users, the definition name is fp_rtn_file_info_tape_2_type. 

• For COBOL users, the definition name is FP-RTN-FILE-INFO-LONG-2. 

• For FORTRAN users, the definition name is FP$RTN$FILL2. 

If you modify an existing ACQ_FILE_LIST function to use an INTERFACE_LEVEL value of 

FP_INTERFACE_LEVEL_2, you must also modify the long form return information 

definition to use the new definition name. For compatibility, the previous definition 

names are unchanged and describe the interface level 1 return information. The format 

of the interface level 1 return information is described in comments in the previous 

definitions. 

The contents of each return entry produced by this function vary depending on what the 

calling program has specified in the function packet, and on the type of file the entry 

describes. For a calling program written in C, all entries produced by a single call to this 

function are not necessarily the same size. When all entries are the same size, the size 

is given by the item RTN_ENTRY_SIZE in the GENERIC PART of the function packet. 

When the entries differ in size, RTN_ENTRY_SIZE has a value of zero. In either case, the 

item FULL_ENTRY_SIZE in each return entry gives the size of that return entry. 

Unlike other PCFP functions that return repeating information, the ACQ_FILE_LIST 

function does not continue processing once it determines that a return entry will not fit 

in the return area. In this case, it immediately returns the error code 

fp_err_small_return_area (decimal1062) in the function packet ERROR_CODE item. The 

NUM_RTN_ENTRIES item will be one greater than the NUM_ENTRIES_IN_RTN_AREA 

item. 

3–46 7830 9796–013



The following definitions indicate the work area requirement (in words) for the 

ACQ_FILE_LIST function: 

• The size of the work area must always be at least 1,000 words. 

• When SEARCH_SET = CATALOG_DIRECTORY, the minimum space requirement 

(1,000 words) is always sufficient. 

• When SEARCH_SET = ASGD_TO_RUN or KNOWN_TO_RUN, the approximate 

words of space required is given by the following formula: 

(200 + 15 * E +7 * I) 

where: 

E is the total number of external files known to the run. An external file is 

known to the run if it is assigned or if it has an internal name attached. 

I is the total number of internal (@USE) names assigned to the run. 

The minimum work area of 1,000 words, for example, is adequate for a run with 40 

external files and 28 internal file names. The maximum work space of 5,000 words is 

adequate, for example, for a run with 180 external files and 300 internal file names or for 

a run with 250 external files and 150 internal file names. 



function, where the minimum relative address is MIN_DATA_ADDR and the maximum 

relative address is MAX_DATA_ADDR_WITH_PCT, as contained in the copy/include 


7830 9796–013 3–47


3–48 7830 9796–013

Section 4 

Changing File Attributes 

This section describes the following five PCFP functions that change the characteristics 

of a specified file or a specified F-cycle series of files that have been cataloged. 

• Change File Specific Attributes (CHG_FILE) changes directory attributes that apply to 

a single specified file. 

• Change File Cycle (CHG_FILE_CYC) changes the F-cycle limit associated with a 

specified F-cycle series of files. 

• Change File Security (CHG_FILE_SEC) changes security attributes that apply to all 

files of a specified F-cycle series of files. 

• Change File Keys (CHG_FILE_KEYS) changes the read key and/or write key 

associated with all files of a specified F-cycle series of files. 

• Change File Name (CHG_FILE_NAME) changes the qualifier and/or file name 

associated with all files of a specified F-cycle series of files. 

4.1. Change File Specific Attributes (CHG_FILE) 

The CHG_FILE function changes directory attributes that apply to a single file specified 

by the calling program. For a cataloged file, this function can change any or all of the 

following file attributes: 

• Project-id 

• Account-id 

• Rollout-prohibited indicator (V option) 

• Read-only/write-only restrictions on the file 

• Disable statuses of file (that is, it can enable or disable a file) 

• Site information 

The CHG_FILE function can also be used to change an empty, sector-addressable, 

temporary, or cataloged mass storage file to a program file. The caller must have read 

and write access to the file. This is the only case with any of the change file functions 

described in this section where the file contents are changed. All other change file 

functions change only directory attributes. This is also the only case where a change file 

function can operate on a temporary file. 

7830 9796–013 4–1


Note that for a temporary file, the file attribute change options listed above are not 

available. The CHG_FILE function has the following program file initialization options: 

• Initialize the file as a PF, LPF, standard LEPF, or large LEPF. 

• Require PCFP to assign the file exclusively or not. 


The CHG_FILE function has the following parameters, each of which is described in the 

following subsections: 



• Work Area 


The structure of the function packet for CHG_FILE is defined in element FP$CHGFIL. 

See Figure 4–1. 

0 

GENERIC PART 

1 PROJECT_ID 

2 

3 

4 ACCOUNT_ID 

5 

6 ROLLOUT_PROHIBITED INIT_PROGRAM_FILE 

7 DIRECTORY_DISABLE WRITE_DISABLE 

8 BACKUP_DISABLE CACHE_DISABLE 

9 READ_ONLY WRITE_ONLY 

10 a B SITE_INFO 

Figure 4–1. CHG_FILE Function Packet Items 

4–2 7830 9796–013


PROJECT_ID 


Indicates the new project-id for the file. The characters composing this value must 

be from the set A – Z, 0 – 9, hyphen ( - ), and dollar sign ($). A null value indicates 

that PCFP is not to change the project-id of the file. 


ACCOUNT_ID 

Indicates the new account-id for the file125 

The characters composing this value must be from the set A – Z, 0 – 9, period ( . ), 

and hyphen ( - ). A null value indicates that PCFP is not to change the account-id of 

the file. 


ROLLOUT_PROHIBITED 

Indicates how PCFP is to change the rollout-prohibited indicator (V option) for the file. 


NO_CHG = 0 

Causes no change to this indicator. 

SET_OFF = 1 

Turns off this indicator, regardless of its previous setting. 

SET_ON = 2 

Turns on this indicator, regardless of its previous setting. 

INIT_PROGRAM_FILE 

Indicates if PCFP should initialize the file as a program file. 


NONE = 0 

PF = 1 

Causes no file initialization. 

Initialize the file as a standard program file (PF). 

7830 9796–013 4–3


LPF = 2 

Initialize the file as a large program file (LPF). 

STANDARD_LEPF = 3 

Initialize the file as a standard capacity, large element program file (standard 

LEPF). 

LARGE_LEPF = 4 

Initialize the file as a large capacity, large element program file (large LEPF). 

For values other than NONE, the file must be an empty, sector-addressable, temporary, 

or cataloged mass storage file to which the caller has read and write access. Files are 

empty when they are initially created with @ASG or @CAT and when they are erased 

with the PCFP ERS_RAF function of the FURPUR @ERS command. 

DIRECTORY_DISABLE 

Indicates how PCFP is to change the directory-disabled indicator for the file. 


NO_CHG = 0 


SET_OFF = 1 


SET_ON = 2 


WRITE_DISABLE 

Indicates how PCFP changes the write-disabled indicator for the file. 


NO_CHG = 0 


SET_OFF = 1 


4–4 7830 9796–013

SET_ON = 2 


BACKUP_DISABLE 

Indicates how PCFP changes the backup-disabled indicator for the file. 


NO_CHG = 0 


SET_OFF = 1 


SET_ON = 2 


CACHE_DISABLE 

Indicates how PCFP changes the cache-disabled indicator for the file. 


NO_CHG = 0 


SET_OFF = 1 


SET_ON = 2 

READ_ONLY 



Indicates how PCFP changes the read-only indicator (R-option) for the file. 


NO_CHG = 0 


7830 9796–013 4–5


SET_OFF = 1 


SET_ON = 2 

WRITE_ONLY 


Indicates how PCFP changes the write-only indicator (W-option) for the file. 


NO_CHG = 0 


SET_OFF = 1 


SET_ON = 2 


a = CHG_SITE_INFO 

Indicates that PCFP changes the site-information field in the master file directory 

entry for the file. The new value is given by SITE_INFO. (The site-information field 

can be used by a site in any manner it chooses.) 


b = EXCLUSIVE_ASSIGN 

Indicates whether or not the file must be assigned exclusively. This item is intended 

primarily for use with INIT_PROGRAM_FILE values other than NONE. 


SITE_INFO 

Indicates the new value for the site-information field. Must be zero if 

CHG_SITE_INFO = FALSE. 


4–6 7830 9796–013



This file identifier parameter names the file on which the function operates. The named 

file must be a cataloged file if file attribute changes are specified for any of the following 

items: 

• PROJECT_ID 

• ACCOUNT_ID 

• ROLLOUT_PROHIBITED 

• DIRECTORY_DISABLE 

• WRITE_DISABLE 

• BACKUP_DISABLE 

• CACHE_DISABLE 

• READ_ONLY 

• WRITE_ONLY 

• CHG_SITE_INFO 

The named file must be an empty, sector-addressable mass storage file to which the 

caller has read and write access if program file initialization is specified by an 

INIT_PROGRAM_FILE item value other than NONE. 

See 2.3 for a detailed description of this parameter. 


The CHG_FILE function requires 1,000 words for its work area. 

4.2. Change File Cycle Attributes (CHG_FILE_CYC) 

The CHG_FILE_CYC function changes the F-cycle limit associated with a specified 

F-cycle series of files. 

When the cycle limit of an F-cycle series is reduced, files that exist in the F-cycle series 

might fall outside the new limit. The CHG_FILE_CYC function gives you the following 

two options for handling this situation: 

• Make the change and delete the extra files 

• Do not make the change and return an error if the change causes the deletion of any 

files 

When this function deletes extra files, it does so only if all of them can be deleted. 

When it must delete files, the function changes the cycle limit only if it successfully 

deleted the extra files. 

Since the information changed by this function must be the same for all files in an Fcycle 

series, the calling program may not specify a specific F-cycle when it calls this 

7830 9796–013 4–7


function. If the calling program specifies an internal file name for this function, the 

internal file name should not refer to a file with a specific F-cycle. 


The CHG_FILE_CYC function has the following parameters, each of which is described in 

the following subsections: 



• Work Area 


The structure of the CHG_FILE_CYC function packet is defined in element 

FP$CHGFILCYC. See Figure 4–2. 

GENERIC PART 

0 a MAX_F_CYCLES 

1 F_CYCLES_RETAINED F_CYCLES_DELETED 


a = ALLOW_DELETION 

Figure 4–2. CHG_FILE_CYC Function Packet Items 

If the calling program sets this item to TRUE and if this function causes the F-cycle 

limit to become less than the number of F-cycles that currently exist, the change is 

made and the oldest F-cycles are deleted so that the number retained falls within the 

new limit. (If all F-cycles are deleted, the entire F-cycle series is deleted.) If the 

calling program sets this item to FALSE and if the change causes one or more 

F-cycles to be deleted, the function does not change the F-cycle limit, and returns an 

error. 


MAX_F_CYCLES 

Indicates the maximum number of files that can be in the same F-cycle series as this 

file. 


4–8 7830 9796–013

F_CYCLES_RETAINED 


Returns the number of F-cycles that exist after the change is made. This number 

includes files that are cataloged, to-be-cataloged, and to-be-deleted. 

Data Type: unsigned integer range (0 – 32), returned 

F_CYCLES_DELETED 

Returns the number of F-cycles that this function deleted. Always 0 when 

ALLOW_DELETION = FALSE. 

Data Type: unsigned integer range (0 – 32), returned 


The file identifier parameter names the file on which the function operates. The named 

file must be cataloged. Because this function operates on an entire F-cycle series of 

files, the calling program must set F_CYCLE_TYPE in this parameter to UNSPECIFIED. If 

the calling program specifies an internal file name in this parameter, the internal file 

name should not refer to a file with a specific F-cycle. See 2.3 for a description of this 

parameter. 


The amount of work area required by the CHG_FILE_CYC function is the larger of 1,000 

and (600 + 60*N) words, where N is the number by which the F-cycle range is reduced. 

The minimum amount of 1,000 words is sufficient unless the F-cycle range is reduced by 

more than 6. The maximum amount of 2,600 words is sufficient for the worst case. 

7830 9796–013 4–9


4.3. Change File Security Attributes 

(CHG_FILE_SEC) 

The CHG_FILE_SEC function changes security attributes that apply to all files of a 


Because the information that this function changes must be the same for all files in an 

F-cycle series, a program may not specify a specific F-cycle when it calls this function. 

For systems with file ownership configured (SENTRY_CONTROL = TRUE), to change the 

security attributes of a file, you must own the file, the file must be unowned, or you 

must have security administrator privileges. In some cases, the security system restricts 

the security attributes you can change for a file. PCFP returns an error condition any 

time you attempt to change security attributes for which you have insufficient privileges. 

See the Security Administration for ClearPath OS 2200 Help for the requirements for 

changing the security attributes of a file. 

For systems without file ownership configured (SENTRY_CONTROL = FALSE), only the 

privacy state of a file can be changed. 


The CHG_FILE_SEC function has the following parameters, each of which is described in 




• Work Area 

4–10 7830 9796–013



This structure of the function packet for CHG_FILE_SEC is defined in element 

FP$CHGFILSEC. See Figure 4–3. 

GENERIC PART 

0 a b CLEARANCE_LEVEL 

1 


3 

4 PRIVACY 

5 ACR_NAME 

6 ACR_NAME 


a = CHG_CLEARANCE_LEVEL 

Figure 4–3. CHG_FILE_SEC Function Packet Items 

Indicates if PCFP is to change the clearance level of the file. If TRUE, PCFP obtains 

the new value from CLEARANCE_LEVEL. 


b = CHG_FILE_OWNER_USER_ID 

Indicates if PCFP is to change the owner user-id of the file. If TRUE, PCFP obtains 

the new value from FILE_OWNER_USER_ID. 


CLEARANCE_LEVEL 

Indicates the new clearance level of the file. Must be zero unless the calling 

program set CHG_CLEARANCE_LEVEL = TRUE. 


7830 9796–013 4–11



Indicates the user-id of the new owner of the file. Must be null unless the calling 

program set CHG_FILE_OWNER_USER_ID = TRUE. If the calling program set 

CHG_FILE_OWNER_USER_ID = TRUE, a value of null for this item causes the file to 

become unowned. Note that changing the FILE_OWNER_USER_ID may cause the 

security system to remove the ACR for a file, which can change the privacy state of 

the file, even when PRIVACY = NO_CHG is specified. 


PRIVACY 

Indicates how this function is to change the privacy state of the file. If the calling 

program set PRIVACY = SEMIPRIVATE, it must specify a non-null value for 

ACR_NAME. 


NO_CHG = 0 

PRIVATE = 1 

SEMIPRIVATE = 2 

PUBLIC = 3 

ACR_NAME 

Indicates the name of the ACR that PCFP is to attach to the file. The ACR specified 

must be owned by the user-id of the run calling PCFP. The program must set this 

item to an actual ACR name if it also sets PRIVACY = SEMIPRIVATE, or it must set 

this item to null if it sets PRIVACY to any value except SEMIPRIVATE. 





files, the calling program must set F_CYCLE_TYPE in this parameter to UNSPECIFIED. 

See 2.3 for a description of this parameter. 


The CHG_FILE_SEC function requires a work area of 1,000 words. 

4–12 7830 9796–013

4.4. Change File Keys (CHG_FILE_KEYS) 


The CHG_FILE_KEYS function changes the read key and/or write key associated with an 

F-cycle series of files. 



When a program calls this function, it must specify the old keys in the file identifier 

parameter and the new keys in the function packet. 


The CHG_FILE_KEYS function has the following parameters, each of which is described 




• Work Area 


This structure of the CHG_FILE_KEYS function packet is defined in element 

FP$CHGFILKEY. See Figure 4–4. 

GENERIC PART 

0 NEW_READ_KEY 

1 NEW_READ_KEY 

2 NEW_WRITE_KEY 

3 NEW_WRITE_KEY 

Figure 4–4. CHG_FILE_KEYS Function Packet Items 

7830 9796–013 4–13



NEW_READ_KEY 

Indicates the new read key for the file. A value of blanks indicates that PCFP is to 

remove the read key of the file. A value of null indicates that PCFP does not change 

any existing read key for the file. 


NEW_WRITE_KEY 

Indicates the new write key for the file. A value of blanks indicates that PCFP is to 

remove the write key of the file. A value of null indicates that PCFP is not to change 

any existing write key for the file. 







If you are changing the keys of a file that already has a read key or a write key, the calling 

program must specify these in the file identifier. If the calling program does not specify 

them or if it specifies them incorrectly, the Exec will abort the calling program and print 

the following message: 

FAC KEY ERR. 


The CHG_FILE_KEYS function requires a work area of 1,000 words. 

4–14 7830 9796–013

4.5. Change File Name (CHG_FILE_NAME) 


The CHG_FILE_NAME function changes the qualifier and/or file name associated with a 




When a program calls this function, the current file is named by the file identifier 

parameter and the new qualifier and/or file name are specified in the function packet. 

The Exec Administration Reference Manual contains a complete description of 

conditions that must be met for a successful name change and the operational 

considerations and restrictions that can exist because a file can be known by both an old 

and a new name. The most common conditions for a successful name change are 

summarized here: 

• The requester must have delete access to the file. 

• No file in the F-cycle series can be unloaded. 

• No file in the F-cycle series can be on a symbiont queue. 

• The new qualifier and file name cannot currently exist. 

After a successful name change, the following are the most common operational 

considerations and restrictions: 

• Following the name change, the file is marked as not having a current backup. It 

cannot be reverted until it is backed up with the new file name. 

• File assignments and @USE names continue to be associated with the old qualifier 

and old file name. To avoid operational problems we strongly recommend that you 

free all of the files in the F-cycle series and all associated @USE names immediately 

following the CHG_FILE_NAME function. 

• If the name change is performed on a cataloged labeled tape file that was previously 

written without the F file assignment option, the tape cannot be read when assigned 

with the new file name. 


The CHG_FILE_NAME function has the following parameters, each of which is described 




• Work Area 

7830 9796–013 4–15



The structure of the CHG_FILE_NAME function packet is defined in element 

FP$CHGFILNAM. See Figure 4–5. 

0 a b 

1 

GENERIC PART 

2 NEW_QUALIFIER 

3 

4 

5 NEW_FILENAME 

6 

7 

8 QUALIFIER_AFTER_CHG 

9 

10 

11 FILENAME_AFTER_CHG 

12 


a = CHG_QUALIFIER 

Figure 4–5. CHG_FILE_NAME Function Packet Items 

Indicates if the qualifier of the file is to be changed. If TRUE, the qualifier will be 

changed as specified in NEW_QUALIFIER. If FALSE, the qualifier will not be 

changed and NEW_QUALIFIER must be set to a null value. 

Data type: condition 

b = CHG_FILENAME 

Indicates if the file name of the file is to be changed. If TRUE, the file name will be 

changed as specified in NEW_FILENAME. If FALSE, the file name will not be 

changed and NEW_FILENAME must be set to a null value. 

Data type: condition 

4–16 7830 9796–013

NEW_QUALIFIER 


Indicates the new qualifier for the file. A null value specifies a change to the default 

qualifier for the run. A value of spaces specifies a change to the implied qualifier for 

the run. Must be a null value if CHG_QUALIFIER is FALSE. 

Data type: characters (12) 

NEW_FILENAME 

Indicates the new file name for the file. Must be a null value if CHG_FILENAME is 

FALSE. 

Data type: characters (12) 

QUALIFIER_AFTER_CHG 

Indicates the new qualifier for the file, following a successful name change. 

Data type: characters (12), returned 

FILENAME_AFTER_CHG 

Indicates the new file name for the file, following a successful name change. 

Data type: characters (12), returned 







The CHG_FILE_NAME function requires a work area of 1,000 words. 

7830 9796–013 4–17


4–18 7830 9796–013

Section 5 

Copying Between Files 

This section describes the following four functions that copy the contents of one file to 

another file. Because tape files require information different from mass storage files, 

PCFP provides four functions to handle the various combinations of tape and mass 

storage files. 

• The copy RAF to RAF function (COPY_RAF_RAF) copies the contents of one mass 

storage random-access file to another random-access file. 

• The copy RAF to SAF function (COPY_RAF_SAF) copies a mass storage 

random-access file to a tape sequential-access file. 

• The copy SAF to RAF function (COPY_SAF_RAF) copies a logical file from a tape 

sequential-access file to a mass storage random-access file. 

• The copy SAF to SAF function (COPY_SAF_SAF) copies a logical file from one tape 

file to another tape file. 

5.1. Copy RAF to RAF (COPY_RAF_RAF) 

The COPY_RAF_RAF function copies the contents of one mass storage random-access 

file to another random-access file. It handles files on sector-addressable mass storage 

and on word-addressable mass storage. 

The following options are provided with this function: 

• Perform the copy only if the destination file is empty (that is, if the destination file 

has no mass storage allocated to it). Use this option to prevent inadvertent 

destruction of data already in the destination file. 

• If the data copied from the source file is less than the original size of the destination 

file, PCFP can handle the excess mass storage in the destination file in one of the 

following ways: 

− Leave it allocated to the destination file 

− Release it, but only back to the initial reserve of the destination file 

− Release all of it 

Use this option to control the unused part of the destination file. 

• Zero-fill any excess mass storage that is released from the destination file. Use this 

option to ensure that sensitive data previously in the destination file is not released 

to the operating system. 

This function causes exclusive assignment of the destination file, but not the source file. 

7830 9796–013 5–1



The COPY_RAF_RAF function has the following parameters, each of which is described 



• Source File Identifier 

• Destination File Identifier 

• Work Area 


The structure of the COPY_RAF_RAF function packet is defined in element 

FP$CPYRAFRAF. See Figure 5–1. 

GENERIC PART 

0 a c STORAGE_TO_RELEASE 


Figure 5–1. COPY_RAF_RAF Function Packet Items 


a = PREVENT_OVERCOPY 

If TRUE, PCFP ensures that the destination file is empty before it copies any data 

into it. The run of the calling program must have read privileges for the destination 

file if this item is set to TRUE. 


c = ZERO_RELEASED_STORAGE 

Indicates if any excess mass storage released by PCFP during the copy operation is 

to be cleared to zero before it is released. This item has meaning only if the calling 

program sets STORAGE_TO_RELEASE to a value other than NONE. 


5–2 7830 9796–013

STORAGE_TO_RELEASE 


Indicates to what extent PCFP is to release any excess mass storage in the 

destination file. 


NONE = 0 

ALL_BUT_INITIAL_RESERVE = 1 

ALL_STORAGE = 2 

AMOUNT_COPIED 

Returns the number of words of file text that PCFP copied from the source file to the 



5.1.3. Source File Identifier 

The source file identifier parameter names the file from which data is copied. The 

named file must be a mass storage file for which the run of the calling program has read 

privileges. See 2.3 for a description of this parameter. 

5.1.4. Destination File Identifier 

The destination file identifier parameter names the file to which data is copied. The 

named file must be a mass storage file for which the run of the calling program has write 



The size of the work area that the calling program provides for PCFP affects the 

performance of the COPY_RAF_RAF function. Because a large file cannot fit in main 

memory, this function copies a file one buffer at a time. The size of each buffer is 

between 1 and 16 mass storage tracks. I/O is most efficient with large buffers, so PCFP 

allocates the largest buffers possible within the work area that the calling program 

provides. 

If the source file is cataloged mass storage, PCFP uses the MFD device area descriptor 

(DAD) tables to determine the mass storage addresses to be read. For files with many 

DAD tables (fragmented files) this operation is much more efficient when larger DAD 

table buffers are used. When this is the case, PCFP can make use of additional work 

area for DAD table buffers. 

The following formula indicates the number of words of work area that PCFP can use so 

that buffers N tracks in size (1


When the source file is a temporary file or a small or unfragmented cataloged file, a 

value of 800 should be used for the constant K. This value allows at least 168 words to 

be allocated for DAD table buffers, for all values of N. 

When the source file is a large or fragmented cataloged file, a value of 2,500 should be 

used for the constant K. This value allows at least 1,792 words to be allocated for DAD 

table buffers, for all values of N. 

The minimum work area size for this function is 4,500 words and allows PCFP to allocate 

buffers one track in size and to allocate at least 168 words for DAD table buffers. The 

maximum work area size for this function is 63,000 words and allows PCFP to allocate 

buffers 16 tracks in size and to allocate the maximum size DAD table buffer, 4,088 

words. 

There is little advantage to the calling program supplying this function with a work area 

larger than this maximum. 

If you expect to use the COPY_RAF_RAF function in the calling program to copy only 

small files (less than 50 tracks), a small work area size (1 to 4 tracks) is acceptable. 

However, if you expect that the files the calling program copies with this function might 

be large, a work area large enough for buffers 8 to 16 tracks in size is recommended. 

The larger the buffer size you allow, the faster the copy operation will complete. For 

very large files, always use the maximum work area size. 

5.2. Copy RAF to SAF (COPY_RAF_SAF) 

The COPY_RAF_SAF function copies a mass storage random-access file to a tape 

sequential-access file. The file is written to tape using the FURPUR (COPY,G) format. 

After this function executes, the tape file is positioned at its logical end, ready to copy 

another file. This operation always writes a hardware EOF mark at the end of the logical 

file. 

The COPY_RAF_SAF function provides the following options: 

• Write the logical file to the tape using either the revised or the obsolete variant of the 

FURPUR tape format. The revised variant allows PCFP to operate more efficiently 

when it later reads the tape file, but the revised variant cannot be read by versions of 

the FURPUR processor level 30R1 or lower. 

• For the revised FURPUR format, the calling program can specify the size of the 

physical blocks to be written, or allow PCFP to choose the size of the physical 

blocks. For the obsolete FURPUR format, the calling program cannot choose the 

size of the physical blocks. 

5–4 7830 9796–013


• If the COPY_RAF_SAF function attempts to swap beyond the last volume of the 

destination file (because PCFP reaches the physical end of the last volume before all 

the data is copied), PCFP takes one of the following actions: 

− Returns with error status. (In this case, the tape is left positioned at the end of 

its last volume.) 

− Dynamically extends the tape file. (To accomplish this, PCFP solicits the 

operator to mount and identify the volume to be appended to the file.) 

• PCFP can calculate and save checksum values for each track of the logical file that it 

writes to the destination file. (If checksum values are not saved with the logical file, 

checksum checking is automatically bypassed when the logical file is subsequently 

read by PCFP.) 

• For a destination file on unlabeled tape, PCFP does one of the following: 

− Writes only a single EOF mark to delimit the end of the logical file. (If this 

alternative is chosen, the CLOSE_SAF function should be called if no further 

logical files are written to the tape. Failure to do so means that the logical end 

cannot be detected on a subsequent read of the tape.) 

− Writes two consecutive EOF marks following the logical file, and backspaces the 

tape so that it is positioned between the EOF marks. The consecutive EOF 

marks indicate the logical end of tape, while the backspacing means that writing 

a subsequent logical file to the tape will overwrite the logical end mark. (If this 

alternative is chosen, there is no need to call CLOSE_SAF.) 

Note that both alternatives apply to all types of unlabeled tape, including 

quarter-inch cartridge tape. 

• Return the block-id that corresponds to the beginning of the destination file. The 

block-id can be saved and used later with the MOVE_SAF function to quickly position 

the tape to the beginning of the file. 

• After completing the copy, ensure that all data has been written from the tape buffer 

to the physical destination tape. This is known as synchronizing the host system and 

the tape drive and is normally done at the end of each tape file by the Exec or by the 

tape subsystem. However, when the BUFTAP buffered-write mode is enabled for 

the destination tape, the Exec improves tape write performance by inhibiting this 

synchronization. Then, it is your responsibility to perform the synchronization when 

desired to establish checkpoints in case a tape write error is reported later. This 

option is provided to allow you to select when to perform the synchronization. 

7830 9796–013 5–5


Before the COPY_RAF_SAF function is used, the current position of the destination file 

must be one of the following: 

• At the load point. In this case, this function obliterates any logical files that might 

have previously been copied to the tape file. 

• At the start of a logical file previously copied to the tape. (That is, the tape must be 

positioned immediately following the EOF mark that delimits the start of a logical 

file.) In this case, this function obliterates the logical file at which the tape is 

positioned, and any subsequent logical files. Logical files prior to the current position 

of the tape are left intact. 

• At the logical end of the tape. (That is, following the last logical file on the tape.) In 

this case, all logical files previously on the tape are left intact. Note that a tape file is 

always positioned at its logical end following a successful copy of a logical file to the 

tape. 

If the current position of the tape is in the middle of a logical file (that is, not immediately 

following an EOF mark), this function returns error code fp_err_not_after_eof, and copies 

nothing to the tape. To handle this situation, you can reposition the tape using the 

MOVE_SAF function. 

The COPY_RAF_SAF function returns the following information concerning the 

destination tape file. 

• Identifiers of all the volumes on which the logical file was written. 

• Volume-relative position of the initial (possibly only) part of the logical file. 

• Number of mass storage words copied. 


The COPY_RAF_SAF function has the following parameters, which are discussed next in 

this section. 




• User Descriptor Data 

• Return Entry 

• Work Area 

5–6 7830 9796–013


The structure of the COPY_RAF_SAF function packet is defined in element 

FP$CPYRAFSAF. See Figure 5–2. 

0 a b c d 

GENERIC PART 


1 DEST_FORMAT DEST_BLOCK_SIZE 


2 ON_END_OF_DEST_FILE 

3 

4 

5 

6 

7 




Figure 5–2. COPY_RAF_SAF Function Packet Items 




• If this item is set to FP_INTERFACE_LEVEL_1, then 

− RETURN_BLOCK_ID must be FALSE. 

− SYNCHRONIZE must be FALSE. 

− The return entry has a format different than that described in 5.2.6. 





7830 9796–013 5–7


a = OMIT_LOG_END_MARK 

This item is applicable only for destination files on unlabeled tapes. It is ignored for 

destination files on labeled tapes. A value of FALSE indicates that PCFP is to write a 

logical end mark, a mark composed of two consecutive EOF marks, following the 

logical file on the destination tape file. In this case, PCFP repositions the tape 

between the EOF marks, so that a subsequent copy overwrites the second EOF 

mark. A value of TRUE indicates that PCFP is to write only a single EOF mark to 

delimit the end of the logical file. In this case, it is the responsibility of the calling 

program to call the CLOSE_SAF function after it has copied the last file to the tape. 


b = SAVE_CHECKSUMS 

If TRUE, PCFP calculates and saves a checksum value for each track of the logical 

file it writes to the destination file. If this item is FALSE, PCFP does not calculate a 

checksum value for each track. This item must be TRUE if the calling program also 

sets WRITE_OBSOLETE_VARIANT to TRUE, and the logical file is to be read 

subsequently by the FURPUR processor (@COPY,G command). 


c = WRITE_OBSOLETE_VARIANT 

If TRUE, PCFP writes the obsolete variant of the FURPUR format to the destination 

file, instead of the revised variant. This item can be TRUE only if the calling program 

set DEST_BLOCK_SIZE = 0 or 1. 


d = RETURN_BLOCK_ID 

If TRUE, PCFP returns the block-id corresponding to the beginning of the destination 

file in the return entry (see 5.2.6). This item can be TRUE only if INTERFACE_LEVEL 

has a value of at least FP_INTERFACE_LEVEL_2. 


5–8 7830 9796–013

e = SYNCHRONIZE 


If TRUE and if the buffered-write mode BUFTAP is enabled, after writing the logical 

file, ensure that all buffered data has been successfully written to tape. If necessary, 

a synchronize (FSAFE$) I/O function is issued. Note that synchronization increases 

the time to write this file, as if the buffered-write mode BUFFIL was enabled. To 

maximize performance, this item should be set to TRUE only periodically to establish 

error recovery checkpoints. This item is ignored if the buffered-write mode is 

BUFOFF, BUFON, or BUFFIL. This item is also ignored for unlabeled tapes when 

OMIT_LOG_END_MARK is FALSE. In these cases, the system and the tape are 

implicitly synchronized by the Exec or by the tape subsystem. This item can be 

TRUE only if INTERFACE_LEVEL has a value of at least FP_INTERFACE_LEVEL_3. 


DEST_FORMAT 

Indicates the format of the logical file that PCFP writes to the destination SAF. 


FURPUR = 1 (This is currently the only legal value for this item.) 

DEST_BLOCK_SIZE 

A nonzero value indicates the size of the physical blocks (in tracks) that PCFP writes 

to the tape file. If the value 0 is specified, PCFP chooses the block size for the 


Data Type: integer range (0 – 16) 

7830 9796–013 5–9


ON_END_OF_DEST_FILE 

Indicates what action PCFP takes if it encounters the physical end of the last volume 

of the destination tape file before it completes the copy operation. 


RTN_ERROR = 0 

Indicates that PCFP does not complete the copy operation and returns an error 

status to the calling program. 

EXTEND_TO_BLANK_VOLUME = 1 

Indicates that PCFP extends the tape file by requesting a BLANK volume. 

System actions on this request depend on many factors, including but not 

limited to 

• Labeled or unlabeled tape 

• Specifications on the tape file @ASG 

• Freestanding or library tape unit 

• System configuration parameters 

• Presence of Media Manager 

• Site unique procedures 

For compatibility, the previous value name SOLICIT_OPR can also be used. 

AMOUNT_COPIED 

Returns the number of words of file text copied from the source file to the 





named file must be a mass storage file for which the run of the calling program has read 




named file must be a tape file for which the run of the calling program has write 

privileges. See 2.3 for a detailed description of this parameter. 

5.2.5. User Descriptor Data 

The user descriptor data parameter is currently unused and must be null. 

5–10 7830 9796–013

5.2.6. Return Entry 


The layout and item descriptions of the return entry for COPY_RAF_SAF are defined 

below. This function produces one return entry that gives information about the 

placement of the logical file on the destination SAF. This return entry is defined in 

element FP$RTN$SAFI. See Figure 5–3. 

Note: Figure 5–3 shows the new format that is returned when INTERFACE_LEVEL has 

a value of at least FP_INTERFACE_LEVEL_3. New return entry definitions must be used 

when using the new interface level. 

• For C users, the definition name is fp_rtn_saf_info_3_type. 

• For COBOL users, the definition name is FP-RTN-SAF-INFO-3. 

• For FORTRAN users, the definition name is FP$RTN$SAFI3. 

If you modify an existing COPY_RAF_SAF or COPY_SAF_SAF function to use an 

INTERFACE_LEVEL value of FP_INTERFACE_LEVEL_3, you must also modify the return 

entry definition to use the new definition name. For compatibility, the previous definition 

names are unchanged and describe the interface level 1 and 2 return entries. The format 

of the interface level 1 and 2 return entries is described in the previous definitions. 

7830 9796–013 5–11


0 RESULT_INDICATOR 

1 NUM_VOLS ENTRY_SIZE 


3 BLOCK_ID 

4 VOL_ID 

5 VOL_ID 

6 FRAGMENT_SIZE 

… . . . 

3n+1 VOL_ID 

3n+2 VOL_ID 

3n+3 FRAGMENT_SIZE 

Figure 5–3. COPY_RAF_SAF and COPY_SAF_SAF Return Entry Items 


RESULT_INDICATOR 

Indicates whether the copy to the destination file was successful, and if not, why 

not. PCFP sets this item to a value other than FP_ERR_NONE (0) if the copy 

operation to the tape file was not completed. The returned value is an ELMS 

condition-id that indicates the reason the operation was not performed. 

Data Type: ELMS condition-id 

NUM_VOLS 

Indicates the number of volumes of the destination file that were required to contain 

the logical file. 


ENTRY_SIZE 

Indicates the total size in words of this return entry. 



Indicates the volume-relative position of the first (possibly only) part of the logical file 

written to the destination tape file. 


5–12 7830 9796–013

BLOCK_ID 


Indicates the block-id that corresponds to the beginning of the logical file. This item 

can have the following values: 

• Zero when the function packet RETURN_BLOCK_ID item is FALSE 

• Negative one (-1) if fast tape access is not supported for the destination SAF 

• A positive integer for valid block-ids 

A valid block-id can be saved and used later with the MOVE_SAF function to quickly 

position the SAF to the beginning of this logical file. 

Data Type: signed integer 

VOL_ID array (1:n) 

Indicates the identifier of the volume of the destination file containing the nth part of 

the logical file. The number of entries in this array equals NUM_VOLS. 


FRAGMENT_SIZE array (1:n) 


Indicates the amount of file text (in words) written to the volume of the destination 

file that contains the nth fragment of the logical file. The number of entries in this 

array equals NUM_VOLS. 



performance of the COPY_RAF_SAF function. Because a large file cannot fit in main 




provides. 

If the source file is cataloged mass storage, PCFP uses the MFD (DAD) tables to 

determine the mass storage addresses to be read. For files with many DAD tables 

(fragmented files) this operation is much more efficient when larger DAD table buffers 

are used. When this is the case, PCFP can make use of additional work area for DAD 

table buffers. 

The following formula indicates the number of words of work area that PCFP can use so 

that buffers N tracks in size (1


When the source file is a temporary file or a small or unfragmented cataloged file, a 

value of 800 should be used for the constant K. This value allows at least 168 words to 

be allocated for DAD table buffers, for all values of N. 

When the source file is a large or fragmented cataloged file, a value of 2500 should be 

used for the constant K. This value allows at least 1,792 words to be allocated for DAD 

table buffers, for all values of N. 

The minimum work area size for this function is 4,500 words and allows PCFP to allocate 

buffers one track in size and to allocate at least 168 words for DAD table buffers. The 

maximum work area size for this function is 63,000 words and allows PCFP to allocate 

buffers 16 tracks in size and to allocate the maximum size DAD table buffer, 4,088 

words. 

There is little advantage to the calling program supplying this function with a work area 

larger than this maximum. 

If you expect to use this function in the calling program to copy only small files (less than 

50 tracks), a small work area size (1 to 4 tracks) is acceptable. However, if you expect 

that the files the calling program copies with this function might be large, a work area 

large enough for buffers 8 to 16 tracks in size is recommended. The larger the buffer 

size you allow, the faster the copy operation will complete. For very large files, always 

use the maximum work area size. 

In addition to performance considerations, the work area must be large enough to allow 

buffers at least as large as the size of the physical blocks written to the tape. The work 

area is used most effectively if the buffer size is a multiple of the physical block size. For 

example, if the physical block is 4 tracks, the size of the work area must be at least 

15,600 words when K is 800 (800 + 3,700*4) or 17,300 words when K is 2,500 (2,500 + 

3,700*4). A work area allowing buffers 4, 8, 12, and 16 tracks in size would be most 

effective for this example. When K is 800 the work area size would be respectively 

15,600, 30,400, 45,200, and 60,000 words. When K is 2,500 the work area size would 

be respectively 17,300, 32,100, 46,900, and 61,700 words. 

5.3. Copy SAF to RAF (COPY_SAF_RAF) 

The COPY_SAF_RAF function copies a logical file from a tape sequential-access file to a 

mass storage random-access file. The tape file must be positioned at the logical file to 

be copied before this function is called. The logical file being copied from the tape must 

be in the revised or obsolete variant of the FURPUR (COPY,G) format. 

After this function has completed successfully, the tape file is positioned at the next 

logical file on the tape. 

The COPY_SAF_RAF function has the following options: 

• Return to the calling program a description of the logical file that was copied. 

• Perform the copy only if the destination file is initially empty (that is, has no mass 

storage allocated to it). Use this option to prevent inadvertent destruction of the 

data already in the destination file. 

5–14 7830 9796–013


• If the data copied from the source file is less than the original size of the destination 

file, PCFP can handle the excess mass storage in the destination file in one of the 

following ways: 

− Leaves it allocated to the destination file 

− Releases it, but only back to the initial reserve of the destination file 

− Releases all of it 

Use this option to control the unused part of the destination file. 

• Zero-fill any excess mass storage that is released from the destination file. Use this 

option to ensure that sensitive data previously in the destination file is not released 

to the operating system. 

• If this function attempts to swap beyond the last volume of the source tape file 

(because the physical end of the last volume is reached before the end of the logical 

file), PCFP takes one of the following actions: 

− Returns with error status. (In this case, the tape file is left positioned at the end 

of the last volume.) 



• If a checksum error is detected while reading the source file, PCFP either proceeds 

with the copy or returns in error. If you choose the first alternative, PCFP returns the 

total number of checksum errors that it detects. In either case, PCFP returns the 

number of the track causing the first checksum error. 

• If a track sequence error is detected on the source file, PCFP either proceeds with 

the copy or returns in error. If you choose the first alternative, PCFP returns the total 

number of track sequence errors that it detects. In either case, PCFP returns the 

number of the track causing the first track sequence error. 

• Return the block-id that corresponds to the beginning of the source file. The block-id 

can be saved and used later with the MOVE_SAF function to quickly position the 

tape to the beginning of the file. 

Before the COPY_SAF_RAF function is used, the current position of the source file can 

be anywhere within the logical file to be copied. If necessary, this function repositions 

the tape to the start of the logical file before copying data from the tape. There are two 

exceptions for which this function cannot reposition to the start of the logical file: 

• The logical file is split across volumes, and the start of the logical file is on a previous 

volume. PCFP cannot swap volumes in the backward direction. 

• The tape file is on quarter-inch cartridge (QIC24). Such a tape cannot be moved 

backward. 

For either of these cases, the COPY_SAF_RAF function returns an appropriate error code 

and does not copy any data. 

7830 9796–013 5–15



The COPY_SAF_RAF function has the following parameters, each of which is described 





• Descriptor Return Area 

• Work Area 


This structure of the COPY_SAF_RAF function packet is defined in element 

FP$CPYSAFRAF. See Figure 5–4. 

GENERIC PART 

0 a c d f g STORAGE_TO_RELEASE 

1 ON_END_OF_SOURCE_FILE NUM_DEST_FILES 

2 

3 DESC_RTN_AREA_SIZE 

4 

5 

6 


8 NUM_CHECKSUM_ERRORS 

9 NUM_TRACK_SEQ_ERRORS 

10 LOC_FIRST_CHECKSUM_ERROR 

11 LOC_FIRST_TRACK_SEQ_ERROR 

12 

Figure 5–4. COPY_SAF_RAF Function Packet Items 

5–16 7830 9796–013






FP_INTERFACE_LEVEL_2. If this item is set to FP_INTERFACE_LEVEL_1, the item 

RETURN_BLOCK_ID must be FALSE and the descriptor return area has a format 

different than that described in 5.3.5. 


a = PREVENT_OVERCOPY 





c = PROCESS_CHECKSUM_ERRORS 

Indicates whether processing continues if PCFP detects a checksum error during the 

copy operation. 


d = PROCESS_TRACK_SEQ_ERRORS 

Indicates whether processing continues if PCFP detects a track sequence error 

during the copy operation. 


f = ZERO_RELEASED_STORAGE 

Indicates whether PCFP clears any excess mass storage released during the copy 

operation. This item has meaning only if the calling program set 

STORAGE_TO_RELEASE to a value other than NONE. 


g = RETURN_BLOCK_ID 

If TRUE, PCFP returns in the descriptor return area (see 5.3.5) the block-id that 

corresponds to the beginning of the source file. This item can be TRUE only if 



7830 9796–013 5–17



Indicates to what extent PCFP releases excess mass storage from the destination 

file. 


NONE = 0 



ON_END_OF_SOURCE_FILE 

Indicates what action to take if PCFP encounters the physical end of the last volume 

of the tape file before the end of the logical file. 


RTN_ERROR = 0 

Indicates that PCFP positions the tape file at the physical end of the last volume, 

and returns an error status to the calling program. 




limited to the following: 








NUM_DEST_FILES 

The calling program must always set this item to 1. 


5–18 7830 9796–013

DESC_RTN_AREA_SIZE 


Indicates the size of the parameter Descriptor Return Area into which PCFP is to 

place the description of the logical file read from the tape file. If this item is zero, 

PCFP ignores the parameter Descriptor Return Area and does not return the 

description of the logical file to the calling program. To have PCFP return the entire 

description of the logical file, the calling program must set this item to 14. 


AMOUNT_COPIED 

Indicates the number of words of file text PCFP copied from the source file to the 



NUM_CHECKSUM_ERRORS 

Indicates the total number of checksum errors PCFP detected while reading the tape 

file. This item can have a value greater than 1 only if the calling program set 

PROCESS_CHECKSUM_ERRORS = TRUE. 


NUM_TRACK_SEQ_ERRORS 

Indicates the total number of track sequence errors PCFP detected while reading the 

tape file. This item can have a value greater than 1 only if the calling program set 

PROCESS_TRACK_SEQ_ERRORS = TRUE. 


LOC_FIRST_CHECKSUM_ERROR 

Indicates the number of the track in which PCFP detected the first checksum error 

while reading the logical file from tape. This value is nonzero only if 

NUM_CHECKSUM_ERRORS > 0. 


LOC_FIRST_TRACK_SEQ_ERROR 

Indicates the number of the track in which PCFP detected the first track sequence 

error while reading the logical file from tape. This value is nonzero only if 

NUM_TRACK_SEQ_ERRORS > 0. 


7830 9796–013 5–19




named file must be a tape file for which the run of the calling program has read 

privileges. See 2.3 for a full description of this parameter. 


This destination file identifier parameter names the file to which data is copied. The 

named file must be a mass storage file for which the run of the calling program has write 


5.3.5. Descriptor Return Area 

With this parameter, PCFP returns the description of the logical file read from the tape 

file. The size of this parameter is given by the item DESC_RTN_AREA_SIZE in the 

function packet. Whenever DESC_RTN_AREA_SIZE = 0, PCFP ignores this parameter 

and does not return the description of the logical file to the calling program. To return 

the entire logical file description, the calling program must provide an area that is at least 

15 words long. The descriptor return area is defined in element FP$RTN$SAFD. 

Note: Figure 5–5 shows the new format that is returned when INTERFACE_LEVEL has 

a value of at least FP_INTERFACE_LEVEL_2. New definitions must be used when using 

the new interface level. 

• For C users, the new definition name is fp_rtn_saf_desc_2_type. 

• For COBOL users, the new definition name is FP-RTN-SAF-DESC-2. 

• For FORTRAN users, the new definition name is FP$RTN$SAFD2. 

If you modify an existing COPY_SAF_RAF or COPY_SAF_SAF function to use an 

INTERFACE_LEVEL value of FP_INTERFACE_LEVEL_2, you must also modify the 

descriptor return area definition to use the new definition name. For compatibility, the 

current definition names are unchanged and describe the interface level1 descriptor 

return area. The format of the interface level1 descriptor return area is described in 

comments contained in the current definitions. 

5–20 7830 9796–013

0 FORMAT BLOCK_SIZE 

1 VOL_ID 

2 VOL_ID a 


4 BLOCK_ID 

5 DATE_TIME_COPIED 

6 

7 

8 QUALIFIER 

9 

10 

11 FILENAME 

12 




Figure 5–5. Descriptor Return Area for COPY_SAF_RAF and 

COPY_SAF_SAF 


FORMAT 

Indicates the format of the logical file PCFP reads from the tape. 


FURPUR = 1 

BLOCK_SIZE 

VOL_ID 

This is the only possible value for this item at this time. 

Indicates the size of the physical blocks (in tracks) in the logical file. 


Indicates the identifier of the tape volume. (If the logical file is split across volumes, 

this information pertains to the initial part of the logical file.) 


7830 9796–013 5–21


a = LOCATE_BLOCK 

Indicates if the tape has been positioned using the Locate Block (LBLK$) I/O function 

issued either by the PCFP MOVE_SAF function or by a caller application. If TRUE, 

the LOGICAL_FILE_POSITION is unknown and is set to zero. 



Indicates the volume-relative position of the logical file. (If the logical file is split 

across volumes, this information pertains to the initial part of the logical file.) 


BLOCK_ID 

Indicates the block-id that corresponds to the beginning of the logical file. This item 



• Negative one (-1) if fast tape access is not supported for the source SAF 

• Negative two (-2) if this is a labeled tape that is positioned to its logical end 


A valid block-id can be saved and used later with the MOVE_SAF function to quickly 

position the SAF to the beginning of this logical file. 


DATE_TIME_COPIED 

Indicates the date and time the logical file was copied to the tape. 


QUALIFIER 

Indicates the qualifier of the mass storage file from which the logical file was copied. 


FILENAME 

Indicates the file name of the mass storage file from which the logical file was 

copied. 


5–22 7830 9796–013

F_CYCLE_TYPE 


Indicates whether F_CYCLE contains an absolute F-cycle value or a relative F-cycle 

value. This item usually has the value ABS. However, if the logical file was copied 

from a temporary mass storage file assigned with a relative F-cycle, this item has the 

value REL. 



Indicates the F-cycle was not saved when the file was copied to tape. 

ABS = 1 

REL = 2 

F_CYCLE 

Indicates the F-cycle of the mass storage file from which the logical file was copied. 


Possible values are as follows: 

If F_CYCLE_TYPE = ABS, the F_CYCLE range is 1 to 999. 

If F_CYCLE_TYPE = REL, the F_CYCLE range is -31 to 1. 

HIGHEST_WORD_WRITTEN 


Indicates the location of the highest word of mass storage written in the logical file. 



performance of the COPY_SAF_RAF function. Because a large file cannot fit in main 




provides. 

The following formula indicates the number of words of work area that PCFP requires so 

that buffers N tracks in size (1 ≤ N ≤ 16) are allocated: 

Work Area Size = 800 + (3700 * N) 

7830 9796–013 5–23


The minimum work area size for this function (4,500 words) allows PCFP to allocate 

buffers one track in size. The maximum work area size for this function (60,000 words) 

allows PCFP to allocate buffers 16 tracks in size. There is no advantage to the calling 

program supplying this function with a work area larger than this maximum. 

If you expect to use the COPY_SAF_RAF function in the calling program to copy only 







buffers at least as large as the size of the physical blocks read from the tape. The work 

area is used most effectively if the buffer size is a multiple of the physical block size. For 

example, if the physical block is 4 tracks, the size of the work area must be at least 

15,600 words (800 + 3700*4). A work area with a size of 15,600, 30,400, 45,200, or 

60,000 words is most effective. 

5.4. Copy SAF to SAF (COPY_SAF_SAF) 

The COPY_SAF_SAF function copies a logical file from one tape file to another tape file. 

The logical file copied must have been written using the FURPUR (COPY,G) format. 

Following execution of this function, the destination tape file is positioned at its logical 

end, ready to accept copying out of another file. This operation always includes writing 

of a hardware EOF mark at the end of the logical file. 

This function has the following options: 

• Return to the calling program a description of the logical file that PCFP copied. 

• Write the logical file to the destination file using either the revised or the obsolete 

variant of the FURPUR tape format. The revised variant allows PCFP to operate 

more efficiently when it later reads the tape file, but the revised variant cannot be 

read by versions of the FURPUR processor level 30R1 or lower. 

• For the revised FURPUR format, the calling program can specify the size of the 

physical blocks to be written, or allow PCFP to choose the size of the physical 

blocks. For the obsolete FURPUR format, the calling program cannot choose the 

size of the physical blocks. 

• If this function attempts to swap beyond the last volume of the source file (because 

PCFP reaches the physical end of the last volume before the end of the logical file), 

or the last volume of the destination file (because PCFP reaches the physical end of 

the last volume before all the data is copied), PCFP takes one of the following 

actions: 

− Returns with error status. (In this case, the tape file remains positioned at the 

physical end of the last volume.) 



5–24 7830 9796–013


• If a checksum error is detected while reading the source file, PCFP either proceeds 

with the copy or returns in error. If you choose the first alternative, PCFP returns the 

total number of checksum errors that it detects. In either case, PCFP returns the 

number of the track causing the first checksum error. 

• If a track sequence error is detected on the source file, PCFP either proceeds with 

the copy or returns in error. If you choose the first alternative, PCFP returns the total 

number of track sequence errors that it detects. In either case, PCFP returns the 

number of the track causing the first track sequence error. 

• PCFP can calculate and save the checksum values for each track of the logical file 

that it writes to the destination file. (If checksum values are not saved with the 

logical file, checksum checking is automatically bypassed when the logical file is 

subsequently read.) 

• For a destination file on an unlabeled tape, PCFP does one of the following: 

− Writes only a single EOF mark to delimit the end of the logical file. (If this 

alternative is chosen, the CLOSE_SAF function should be called if no further 

logical files are written to the tape. Failure to do so means that the logical end 

cannot be detected on a subsequent read of the tape.) 

− Writes two consecutive EOF marks following the logical file, and backspaces the 

tape so that it is positioned between the EOF marks. The consecutive EOF 

marks indicate the logical end of tape, while the backspacing means that writing 

a subsequent logical file to the tape will overwrite the logical end mark. (If you 

choose this alternative, you do not need to call CLOSE_SAF.) 

This option has no effect if the destination file is on a labeled tape. Note that 

both alternatives apply to all types of unlabeled tape, including the quarter-inch 

cartridge tape. 

• Return the block-id that corresponds to the beginning of the source file and the 

block-id that corresponds to the beginning of the destination file. The block-ids can 

be saved and used later with the MOVE_SAF function to quickly position the tape to 

the beginning of either file. 

• After completing the copy, ensure that all data has been written from the tape buffer 

to the physical destination tape. This is known as synchronizing the host system and 

the tape drive and is normally done at the end of each tape file by the Exec or by the 

tape subsystem. However, when the BUFTAP buffered-write mode is enabled for 

the destination tape, the Exec improves tape write performance by inhibiting this 

synchronization. Then, it is your responsibility to perform the synchronization when 

desired to establish checkpoints in case a tape write error is reported later. This 

option is provided to allow you to select when to perform the synchronization. 

Before the COPY_SAF_SAF function is used, the current position of the source file can 

be anywhere within the logical file to be copied. If necessary, this function repositions 

the tape to the start of the logical file before copying data from the tape. There are two 

exceptions for which this function cannot reposition to the start of the logical file: 

• The logical file is split across volumes, and the start of the logical file is on a previous 

volume. PCFP cannot swap volumes in the backward direction. 

• The tape file is on quarter-inch cartridge (QIC24). Such a tape cannot be moved 

backward except to load point on the tape. 

7830 9796–013 5–25


For either of these cases, the COPY_SAF_SAF function returns an appropriate error code 

and does not copy any data. 

Before this function is used, the current position of the destination file must be one of 

the following: 

• At the load point. In this case, this function obliterates any logical files that might 

have previously been copied to the tape file. 

• At the start of a logical file previously copied to the tape. (That is, the tape must be 

positioned immediately following the EOF mark that delimits the start of a logical 

file.) In this case, this function obliterates the logical file at which the tape is 

positioned, and any subsequent logical files. Logical files prior to the current position 

of the tape are left intact. 

• At the logical end of the tape. (That is, following the last logical file on the tape.) In 

this case, all logical files previously on the tape are left intact. Note that a tape file is 

always positioned at its logical end following a successful copy of a logical file to the 

tape. 

If the current position of the destination tape is in the middle of a logical file (that is, not 

immediately following an EOF mark), this function returns error code 

fp_err_not_after_eof, and copies nothing to the tape. To handle this situation, you can 

reposition the tape using the MOVE_SAF function. 

The COPY_SAF_SAF function returns the following information about the destination file: 

• Identifiers of all the volumes on which the logical file was written 

• Volume-relative position of the initial (possibly only) part of the logical file 

• Number of words of file text copied 

Optionally, this function can also return a descriptor of the logical file that was copied 

from the source tape file. The description returned is the same as that returned by 

COPY_SAF_RAF. 


The COPY_SAF_SAF function has the following parameters, which are discussed next in 

this section: 




• User Descriptor Data 


• Descriptor Return Area 

• Work Area 

5–26 7830 9796–013


The structure of the COPY_SAF_SAF function packet is defined in element 

FP$CPYSAFSAF. See Figure 5–6. 

0 b c e g h i 

1 NUM_DEST_FILES 

GENERIC PART 



2 DESC_RTN_AREA_SIZE 

3 

4 DEST_BLOCK_SIZE 

5 ON_END_OF_SOURCE_FILE ON_END_OF_DEST_FILE 

6 

7 

8 

9 

10 


12 NUM_CHECKSUM_ERRORS 

13 NUM_TRACK_SEQ_ERRORS 

14 LOC_FIRST_CHECKSUM_ERROR 

15 LOC_FIRST_TRACK_SEQ_ERROR 

16 

Figure 5–6. COPY_SAF_SAF Function Packet and Return Area Items 

7830 9796–013 5–27








− RETURN_BLOCK_ID must be FALSE. 


− The descriptor return entry has a format different than that described in 

5.3.5. 






b = PROCESS_CHECKSUM_ERRORS 

Indicates whether PCFP continues processing if it detects a checksum error during 

the copy operation. 


c = PROCESS_TRACK_SEQ_ERRORS 

Indicates whether PCFP continues processing if it detects a track sequence error 

during the copy operation. 


e = OMIT_LOG_END_MARK 

This item is applicable only for destination files on unlabeled tapes. It is ignored for 

destination files on labeled tapes. A value of FALSE indicates that PCFP is to write a 

logical end mark, a mark composed of two consecutive EOF marks, following the 

logical file it writes on the destination SAF. In this case, PCFP repositions the tape 

between the EOF marks, so that a subsequent copy overwrites the second EOF 

mark. A value of TRUE indicates that PCFP is to write only a single EOF mark to 

delimit the end of the logical file. In this case, it is the responsibility of the calling 

program to call the CLOSE_SAF function after copying the last file to the tape. 


5–28 7830 9796–013

g = SAVE_CHECKSUMS 


If TRUE, PCFP calculates and saves a checksum value for each track of the logical 

file written to the destination file. If this item is FALSE, PCFP does not calculate a 

checksum value for each track. The calling program must set this item to TRUE if it 

also sets WRITE_OBSOLETE_VARIANT to TRUE, and the logical file is to be read 

subsequently by the FURPUR processor. 


h = WRITE_OBSOLETE_VARIANT 

If TRUE, this indicates that PCFP is to write the obsolete variant of the FURPUR 

format to the destination file, instead of the revised variant. This item can be TRUE 

only if the calling program sets DEST_BLOCK_SIZE = 0 or 1. 


i = RETURN_BLOCK_ID 

If TRUE, PCFP returns, in the descriptor return area (see 5.3.5), the block-id 

corresponding to the beginning of the source file, and in the return entry (see 5.2.6), 

the block-id corresponding to the beginning of the destination file. This item can be 



j = SYNCHRONIZE 


file, ensure that all buffered data has been successfully written to tape. If necessary, 

a synchronize (FSAFE$) I/O function is issued. Note that synchronization increases 

the time to write this file, as if the buffered-write mode BUFFIL was enabled. To 

maximize performance, this item should be set to TRUE only periodically to establish 

error recovery checkpoints. This item is ignored if the buffered-write mode is 

BUFOFF, BUFON, or BUFFIL. This item is also ignored for unlabeled tapes when 

OMIT_LOG_END_MARK is FALSE. In these cases, the system and the tape are 

implicitly synchronized by the Exec or by the tape subsystem. This item can be 



NUM_DEST_FILES 

The calling program must always set this item to 1. 


7830 9796–013 5–29


DESC_RTN_AREA_SIZE 

Indicates the size of the parameter Descriptor Return Area into which PCFP is to 

place the description of the logical file it reads from the source file. If this item is 

zero, PCFP ignores the parameter Descriptor Return Area and does not return the 

descriptor of the logical file to the calling program. 


DEST_BLOCK_SIZE 

A nonzero value indicates the size of the physical blocks (in tracks) that PCFP writes 

to the destination SAF. If the calling program sets this item to zero, PCFP chooses 

the block size for the destination file. 


ON_END_OF_SOURCE_FILE 

Indicates the action PCFP takes if it encounters the physical end of the last volume 

of the source tape file before the end of the logical file. 


RTN_ERROR = 0 

Indicates that PCFP positions the file at the physical end of the last volume and 

returns an error status to the calling program. 












5–30 7830 9796–013

ON_END_OF_DEST_FILE 


Indicates the action PCFP takes if it encounters the physical end of the last volume 

of the destination tape file before completing the copy operation. 


RTN_ERROR = 0 

Indicates that PCFP does not complete the copy operation and returns an error 

status to the calling program. 












All of the following items contain values returned by PCFP: 

AMOUNT_COPIED 

Returns the number of words of file text copied from the source file to the 



NUM_CHECKSUM_ERRORS 

Returns the total number of checksum errors PCFP detected while reading the 

source file tape. This item can have a value greater than 1 only if the calling program 

set PROCESS_CHECKSUM_ERRORS = TRUE. 


7830 9796–013 5–31


NUM_TRACK_SEQ_ERRORS 

Indicates the total number of track sequence errors PCFP detected while reading the 

source tape file. This item can have a value greater than 1 only if the calling program 

set PROCESS_TRACK_SEQ_ERRORS = TRUE. 


LOC_FIRST_CHECKSUM_ERROR 

Indicates the number of the track in which PCFP detected the first checksum error 

while reading the source tape file. This value is nonzero only if 

NUM_CHECKSUM_ERRORS is greater than 0. 


LOC_FIRST_TRACK_SEQ_ERROR 

Indicates the number of the track for which PCFP detected the first track sequence 

error while reading the source tape file. This value is nonzero only if 

NUM_TRACK_SEQ_ERRORS is greater than 0. 




named file must be a tape file for which the run of the calling program has read 

privileges. See 2.3 for a full description of this parameter. 



named file must be a tape file for which the run of the calling program has write 

privileges. See 2.3 for a detailed description of this parameter. 

5.4.5. User Descriptor Data 

The user descriptor data parameter is currently unused and must be null. 


This function produces one return entry that gives information about the placement of 

the logical file on the destination SAF. 

The return entry for this function is the same as for COPY_RAF_SAF. See 5.2.6. 

5–32 7830 9796–013

5.4.7. Descriptor Return Area 


The descriptor return area parameter returns the description of the logical file that this 

function reads from the source tape file. See 5.3.5 for a full description of this 

parameter. 



performance of the COPY_SAF_RAF function. Because a large file cannot fit in main 




provides. 

The following formula indicates the number of words of work area that PCFP requires so 

that buffers N tracks in size (1 ≤ N ≤ 16) are allocated: 

Work Area Size = 800 + (3700 * N) 

The minimum work area size for this function (4,500 words) allows PCFP to allocate 

buffers one track in size. The maximum work area size for this function (60,000 words) 

allows PCFP to allocate buffers 16 tracks in size. There is no advantage to the calling 

program supplying this function with a work area larger than this maximum. 

If you expect to use the COPY_SAF_RAF function in the calling program to copy only 







buffers at least as large as the size of the physical blocks read from the source file and 

written to the destination file. The work area is used most effectively if the buffer size is 

a multiple of the physical block size. For example, if the physical block is 4 tracks, the 

size of the work area must be at least 15,600 words (800 + 3700*4). A work area with a 

size of 15,600, 30,400, 45,200, or 60,000 words is most effective. 

7830 9796–013 5–33


5–34 7830 9796–013

Section 6 

Acquiring Program File Information 

This section describes the following five functions that obtain information about the 

contents of a program file. 

• Acquire Basic Program File Information (ACQ_BASIC_PF_INFO) 

• Acquire Element Information (ACQ_ELT_INFO) 

• Acquire Relocatable Entry Point Information (ACQ_REL_EP_INFO) 

• Acquire Object Module Entry Point Information (ACQ_OM_EP_INFO) 

• Acquire Procedure Information (ACQ_PROC_INFO) 

These functions operate on only sector-addressable mass storage files that have been 

formatted as program files. 

6.1. Acquire Basic Program File Information 

(ACQ_BASIC_PF_INFO) 

The ACQ_BASIC_PF_INFO function returns global information about a specified program 

file. The information returned is not associated with particular elements, entry points, or 

procedures in the program file. Specifically, this function returns the following 

information: 

• An indication if this is an empty file that can be initialized as a program file 

• Next available mass storage location for element text 

• Amount of mass storage occupied by tables of contents in the program file 

• Amount of mass storage occupied by the text of all elements in the program file 

• Amount of mass storage occupied by the text of deleted elements in the program 

file 

• Number of undeleted elements of each type (absolute, omnibus, relocatable, 

symbolic) in the program file 

• Number of deleted elements (of all types) in the program file 

• Sequence number of last undeleted absolute element in the program file 

• Amount of mass storage occupied by the undeleted element with the largest 

amount of text 

• Number of undeleted and deleted symbolic elements of procedure subtype 

7830 9796–013 6–1


• Number of undeleted symbolic elements of procedure subtype 

• Number of undeleted and deleted four-word COBOL procedure table entries 

• Number of undeleted and deleted 8-word COBOL procedure table entries 

• Number of undeleted elements that will be updated if this file is processed with the 

PACK_PF function (see 8.4 for a description of the PACK_PF function) 

• Amount of mass storage that will be copied if this file is processed with the 

PACK_PF function 

• The type of program file (PF, LPF, standard LEPF, or large LEPF) 

• The following information for the element table of contents, each procedure table of 

contents, and the relocatable entry point table of contents: 

− The number of entries currently in the table (both deleted and undeleted entries) 

− The number of additional entries the table can hold at its currently allocated size 

(for the COBOL procedure table of contents, PCFP assumes maximum-size 

entries when it computes this value) 

Note: This information is not returned for the object module entry point table of 

contents, because, for this table, it is prohibitively expensive to determine the number of 

entries, and there is no limit to the number of additional entries that the table can hold. 


The ACQ_BASIC_PF_INFO function has the following parameters, each of which is 

described in the following subsections: 



• Work Area 

6–2 7830 9796–013



The structure of the ACQ_BASIC_PF_INFO function packet is defined in element 

FP$ACQPFINF. See Figure 6–1. 

GENERIC PART 

0 a b 

1 NEXT_TEXT_LOCATION 

2 TOC_SIZE 

3 TEXT_SIZE 

4 LAST_ABS_SEQ_NUM 

5 ELT_NUM_ENTRIES ELT_OPEN_ENTRIES 

6 MASM_PROC_NUM_ENTRIES MASM_PROC_OPEN_ENTRIES 

7 COBOL_PROC_NUM_ENTRIES COBOL_PROC_OPEN_ENTRIES 

8 FTN_PLS_PROC_NUM_ENTRIES FTN_PLS_PROC_OPEN_ENTRIES 

9 REL_EP_NUM_ENTRIES REL_EP_OPEN_ENTRIES 

10 NUM_ABS_ELTS NUM_OMN_ELTS 

11 NUM_REL_ELTS NUM_SYM_ELTS 

12 NUM_DELETED_ELTS 

13 DEAD_SPACE 

14 LARGEST_UNDELETED_TEXT_SIZE 

15 NUM_PROC_ELTS NUM_UNDELETED_PROC_ELTS 

16 NUM_4_WORD_COBOL_PROC_ENTRIES NUM_8_WORD_COBOL_PROC_ENTRIES 

17 PACK_PF_NUM_ELTS_TO_UPDATE PROGRAM_FILE_TYPE 

18 PACK_PF_TEXT_SIZE_TO_COPY 

Figure 6–1. ACQ_BASIC_PF_INFO Function Packet Items 

7830 9796–013 6–3






FP_INTERFACE_LEVEL_2. If this item is set to FP_INTERFACE_LEVEL_1, the item 

EMPTY_FILE and the items in words 14 – 18 will not be returned by the function. 


a = GET_SUMMARY_INFO 

Indicates whether PCFP computes values for the following items: 

• NUM_ABS_ELTS 

• NUM_OMN_ELTS 

• NUM_REL_ELTS 

• NUM_SYM_ELTS 

• NUM_DELETED_ELTS 

• DEAD_SPACE 

• LARGEST_UNDELETED_TEXT_SIZE 

• NUM_PROC_ELTS 

• NUM_UNDELETED_PROC_ELTS 

• PACK_PF_NUM_ELTS_TO_UPDATE 

• PACK_PF_TEXT_SIZE_TO_COPY 

If GET_SUMMARY_INFO = FALSE, a value of zero is returned for each of these 

items. (Computation of these values is optional because of the extra overhead 

involved in determining them.) 


Note: All remaining items in this function packet contain return values. 

6–4 7830 9796–013

= EMPTY_FILE 


Indicates if this is an empty file that can be initialized as a program file by the PCFP 

CHG_FILE, COPY_ELT, COPY_RAF_OMN_ELT, or COPY_RAF_SYM_ELT functions. 

This item is returned only when INTERFACE_LEVEL has a value of at least 


When error code 2602 (fp_err_empty_file) is returned in ERROR_CODE in the 

GENERIC PART of the function packet, this item and PROGRAM_FILE_TYPE are still 

returned and should be interpreted as follows: 

− If EMPTY_FILE is TRUE, this file is empty and it can be initialized as a program 

file. Item PROGRAM_FILE_TYPE will have a value of NONE. 

− If EMPTY_FILE is FALSE, this file is already a program file, but it does not 

contain any elements. Item PROGRAM_FILE_TYPE will specify the type. This 

file cannot be initialized as a program file unless it is erased with the PCFP 

ERS_RAF function or the FURPUR @ERS command. 


NEXT_TEXT_LOCATION 

Indicates the location (in words) where the text of the next element added to the 

program file is written. 


TOC_SIZE 

Indicates the amount of mass storage (in words) currently occupied by the tables of 

contents in the program file. 


TEXT_SIZE 

Indicates the amount of mass storage (in words) currently occupied by the text of all 

elements and all Object Module Entry Point Tables in the program file. 


LATEST_ABS_SEQ_NUM 

Indicates the sequence number of the latest undeleted absolute element in the 

program file. A value of zero implies either that the file contains no absolute 

elements or that the latest absolute element in the program file is marked deleted. 


7830 9796–013 6–5


ELT_NUM_ENTRIES 

Indicates the current number of entries in the element table of contents (deleted and 

undeleted). 


ELT_OPEN_ENTRIES 

Indicates the number of additional entries the element table of contents can contain 

at its currently allocated size. (See notes following item descriptions.) 


MASM_PROC_NUM_ENTRIES 

Indicates the current number of entries in the MASM procedure table of contents 

(deleted and undeleted). 


MASM_PROC_OPEN_ENTRIES 

Indicates the number of additional entries the MASM procedure table of contents 

can contain at its currently allocated size. (See notes following item descriptions.) 


COBOL_PROC_NUM_ENTRIES 

Indicates the current number of entries in the COBOL procedure table of contents 



COBOL_PROC_OPEN_ENTRIES 

Indicates the number of additional entries the COBOL procedure table of contents 

can contain at its currently allocated size. (See notes following item descriptions.) 


FTN_PLS_PROC_NUM_ENTRIES 

Indicates the current number of entries in the FORTRAN-PLUS procedure table of 

contents (deleted and undeleted). 


6–6 7830 9796–013

FTN_PLS_PROC_OPEN_ENTRIES 


Indicates the number of additional entries the FORTRAN-PLUS procedure table of 

contents can contain at its currently allocated size. (See notes following item 

descriptions.) 


REL_EP_NUM_ENTRIES 

Indicates the current number of entries in the relocatable entry point table of 

contents (deleted and undeleted). 


REL_EP_OPEN_ENTRIES 

Indicates the number of additional entries the relocatable entry point table of 

contents can contain at its currently allocated size. (See notes following item 



NUM_ABS_ELTS 

Indicates the number of undeleted absolute elements in the program file. Has a 

value of zero if the calling program set GET_SUMMARY_INFO = FALSE. 


NUM_OMN_ELTS 

Indicates the number of undeleted omnibus elements in the program file. Has a 



NUM_REL_ELTS 

Indicates the number of undeleted relocatable elements in the program file. Has a 



NUM_SYM_ELTS 

Indicates the number of undeleted symbolic elements in the program file. Has a 



7830 9796–013 6–7


NUM_DELETED_ELTS 

Indicates the number of deleted elements of all types in the program file. Has a 



DEAD_SPACE 

Indicates the amount of mass storage (in words) currently occupied by the text of all 

deleted elements and all Object Module Entry Point Tables in the program file. Has 

a value of zero if the calling program set GET_SUMMARY_INFO = FALSE. 


Note: All remaining items in this function packet are returned only when 


LARGEST_UNDELETED_TEXT_SIZE 

Indicates the amount of mass storage (in words) occupied by the text of the 

undeleted element with the largest amount of text. Has a value of zero if the calling 

program set GET_SUMMARY_INFO = FALSE. 


NUM_PROC_ELTS 

Indicates the number of symbolic procedure elements (subtypes ASMP, COBP, 

FORP, and PSP) in the program file (deleted and undeleted). Has a value of zero if 

the calling program set GET_SUMMARY_INFO = FALSE. 


NUM_UNDELETED_PROC_ELTS 

Indicates the number of undeleted symbolic procedure elements (subtypes ASMP, 

COBP, FORP, and PSP) in the program file. Has a value of zero if the calling program 

set GET_SUMMARY_INFO = FALSE. 


NUM_4_WORD_COBOL_PROC_ENTRIES 

Indicates the number of four-word COBOL procedure table entries in the program 

file (deleted and undeleted). 


6–8 7830 9796–013

NUM_8_WORD_COBOL_PROC_ENTRIES 


Indicates the number of 8-word COBOL procedure table entries in the program file 



PACK_PF_NUM_ELTS_TO_UPDATE 

Indicates the number of undeleted elements in the program file that would be 

updated if this file were processed with the PACK_PF function. See C.1 for a 

description of how this value affects PACK_PF function performance. Has a value of 

zero if the calling program set GET_SUMMARY_INFO = FALSE. 


PROGRAM_FILE_TYPE 

Indicates the type of the program file. 


NONE = 0 

PF = 1 

LPF = 2 

The file is not a program file. Returned when EMPTY_FILE is TRUE. 

The file is a standard program file (PF). 

The file is a large program file (LPF). 


The file is a standard capacity, large element program file (standard LEPF). 


The file is a large capacity, large element program file (large LEPF). 

UNSUPPORTED = 6 

The file is a nonstandard program file. 

When error code 2602 (fp_err_empty_file) is returned in ERROR_CODE in the GENERIC 

PART of the function packet, this item is still returned. See EMPTY_FILE for a detailed 

explanation. 

7830 9796–013 6–9


PACK_PF_TEXT_SIZE_TO_COPY 

Indicates the amount of mass storage (in words) that would be copied if this file 

were processed with the PACK_PF function. See C.1 for a description of how this 

value affects PACK_PF function performance. Has a value of zero if the calling 

program set GET_SUMMARY_INFO = FALSE. 


Notes: The following points apply to each item that returns the number of available 

entries in a table of contents: 

• For a standard program file, if a table is empty (current number of entries is zero), the 

value that PCFP returns for the number of available entries in the table is also zero 

even though in most cases entries can be added to the table. 

• For a standard program file, PCFP calculates the number of available entries by 

assuming that all tables that are currently empty remain empty. If an entry is added 

later to a table that is currently empty, the number of entries available in other tables 

might be significantly reduced. 

• For a large program file, all tables have fixed sizes and a fixed maximum number of 

entries. PCFP calculates the number of available entries by subtracting from the 

fixed maximum the number of entries currently in the table. 

• Some tables (for example, the COBOL procedure table) have variable-length entries. 

PCFP calculates the number of available entries by assuming entries of maximum 

size. 


The file identifier parameter names the file from which information is to be acquired. 

The named file must be a program file on sector-addressable mass storage for which the 

calling program has read privileges. See 2.3 for a description of this parameter. 


The ACQ_BASIC_PF_INFO function operates with any work area greater than or equal to 

the minimum size of 1,000 words. When the calling program sets 

GET_SUMMARY_INFO = FALSE, this function never uses a work area larger than this 

minimum. When the calling program sets GET_SUMMARY_INFO = TRUE, the function 

works more efficiently with larger work area sizes. The actual memory usable by the 

function varies with the size of the program file on which it operates. This function can 

make effective use of about 200 + 10*N words, where N is the number of elements 

(deleted and undeleted) in the program file. Thus, a work area size larger than the 

minimum is used with a program file containing more than 80 elements. The maximum 

size work area is used for program files containing about 2,000 or more elements. 

6–10 7830 9796–013


6.2. Acquire Element Information (ACQ_ELT_INFO) 

The ACQ_ELT_INFO function acquires information from a program file about one or 

more elements that meet conditions specified by the calling program. At a minimum, 

this function returns to the calling program the name, version, type, subtype, and 

sequence number of all elements that it selects. This function can select both undeleted 

and deleted elements. 

The element attributes by which PCFP can select elements are described in the 

definition of the function packet. Supplying a value for any attribute further restricts the 

set of elements PCFP selects. The calling program may supply values for as few or as 

many of these attributes as it requires. 

When PCFP selects a list of elements, it assumes no default selection criteria. Unless 

the calling program explicitly specifies a particular attribute, all values of that attribute are 

assumed to qualify. For example, if the calling program must limit the search to a 

particular type of element, it must specify an element type. If the calling program 

specifies no selection criteria, PCFP selects all elements in the program file. 

In some cases, a program may need to acquire more information about elements than 

their names, versions, types, subtypes, and sequence numbers. A notable example of 

this is the @PRT,TL capability of FURPUR. For this reason, the ACQ_ELT_INFO function 

also provides for the return of more extensive information. The full list of information 

obtainable is described in 6.2.4. It includes all information about elements that can be 

obtained using the FURPUR @PRT,TL command. 

The ACQ_ELT_INFO function has an option for limiting the number of element entries 

returned to a specified maximum. If more element entries than the maximum qualify, 

PCFP does not return the excess to the calling program. 


The ACQ_ELT_INFO function has the following parameters, each of which is described 





• Work Area 

7830 9796–013 6–11



0 

1 

2 

3 

4 

5 

10 

11 

12 

13 

6 a b c d 

The structure of the ACQ_ELT_INFO function packet is defined in element 

FP$ACQELTINF. See Figure 6–2. 

GENERIC PART 


ELT_NAME 

ELT_VERSION 

7 e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e 

8 e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e e 

9 f f f f f f f f f f f f f f f f f f CHAR_TYPE 

MIN_DATE_TIME 

MAX_DATE_TIME 

14 MIN_SEQ_NUM 

15 MAX_SEQ_NUM 

16 MIN_SIZE 

17 MAX_SIZE 

18 DELETION INFO_DETAIL 


20 

… 

23 

Figure 6–2. ACQ_ELT_INFO Function Packet Items 

6–12 7830 9796–013 

…


ELT_NAME 


Indicates name or pattern of the name of the elements to be selected. The value 


asterisk ( * ) wild-card characters as described in 2.6. A null value indicates the 

elements are to be selected without regard to their names. 


ELT_VERSION 

Indicates version or pattern of the version of the elements to be selected. The value 


asterisk ( * ) wild-card characters as described in 2.6. A null value indicates the 

elements are to be selected without regard to their versions. 


a = ABS_TYPE 

Indicates whether absolute elements are to be selected. 


b = OMN_TYPE 

Indicates whether omnibus elements are to be selected. 


c = REL_TYPE 

Indicates whether relocatable elements are to be selected. 


d = SYM_TYPE 

Indicates whether symbolic elements are to be selected. 


If items ABS_TYPE, OMN_TYPE, REL_TYPE, and SYM_TYPE are all FALSE, PCFP 

selects elements regardless of their types. 

7830 9796–013 6–13


e = OMN_SYM_SUBTYPE array (0:71) 

Indicates which omnibus and symbolic element subtypes PCFP selects. Each item 

in this array occupies a single bit. If the calling program sets any entries in this array 

to TRUE (1), PCFP limits the omnibus and symbolic elements it selects to those that 

have a numeric subtype corresponding to a TRUE entry. If the calling program sets 

no item in the array to TRUE, PCFP selects omnibus and symbolic elements 

regardless of subtype. This item applies only to symbolic and omnibus elements; 

this item does not affect the selection of elements of other types. 

Data Type: condition array 

f = ABS_SUBTYPE array (0:17) 

Indicates which absolute element subtypes PCFP selects. Each item in this array 

occupies a single bit. If the calling program sets any entries in this array to TRUE (1), 

PCFP limits the absolute elements it selects to those that have a numeric subtype 

corresponding to a TRUE entry. If the calling program sets no item in the array to 

TRUE, PCFP selects absolute elements regardless of subtype. This item applies 

only to absolute elements; this item does not affect the selection of elements of 

other types. 


CHAR_TYPE 

Indicates whether PCFP selects only ASCII or Fieldata elements, or if PCFP selects 

elements regardless of this attribute. This item applies only to symbolic elements; 

this item does not affect the selection of elements of other types. 


BOTH = 0 

ASCII = 1 

Fieldata = 2 

MIN_DATE_TIME 

Indicates whether PCFP selects elements with or without regard to a minimum date 

and time. If this item is nonzero, PCFP selects only elements with a date and time 

of creation greater than or equal to that specified. If this item is zero, PCFP selects 

elements without regard to a minimum date and time. 


6–14 7830 9796–013

MAX_DATE_TIME 


Indicates whether PCFP selects elements with or without regard to a maximum date 

and time. If this item is nonzero, PCFP selects only elements with a date and time 

of creation less than or equal to that specified. If this item is zero, PCFP selects 

elements without regard to a maximum date and time. 


MIN_SEQ_NUM 

Indicates whether PCFP selects elements with or without regard to a minimum 

sequence number. If this item is nonzero, PCFP selects only elements with a 

sequence number greater than or equal to that specified. If this item is zero, PCFP 

selects elements without regard to a minimum sequence number. 


MAX_SEQ_NUM 

Indicates whether PCFP selects elements with or without regard to a maximum 

sequence number. If this item is nonzero, PCFP selects only elements with a 

sequence number less than or equal to that specified. If this item is zero, PCFP 

selects elements without regard to a maximum sequence number. 

If both MAX_SEQ_NUM and MIN_SEQ_NUM have the same nonzero value, PCFP 

selects at most one element. 


MIN_SIZE 

Indicates whether PCFP selects elements with or without regard to a minimum text 

size. If this item is nonzero, PCFP selects only elements with a word size greater 

than or equal to that specified. If this item is zero, PCFP selects elements without 

regard to a minimum size. 


MAX_SIZE 

Indicates whether elements are selected with or without regard to a maximum text 

size. If this item is nonzero, PCFP selects only elements with a word size less than 

or equal to that specified. If this item is zero, PCFP selects elements without regard 

to a maximum size. 


7830 9796–013 6–15


DELETION 

Indicates whether PCFP selects elements regardless of whether or not they are 

deleted, or if PCFP selects only deleted or only undeleted elements. 


UNDELETED = 0 

Indicates that PCFP selects only undeleted elements. 

DELETED = 1 

Indicates that PCFP selects only deleted elements. 

BOTH = 2 

INFO_DETAIL 

Indicates that PCFP selects all elements regardless of whether or not they are 

deleted. 

Indicates the amount of information PCFP returns for each element it selects. 


SHORT = 0 

Indicates that for each element that PCFP selects, it returns only the following 

items: RESULT_INDICATOR, ELT_NAME, ELT_VERSION, ELT_TYPE, 

ELT_SUBTYPE, SEQ_NUM. 

LONG = 1 

Indicates that PCFP returns all information described in 6.2.4 for each element. 

NUM_SELECTED 

Indicates how many elements PCFP selected. 


6–16 7830 9796–013







PCFP returns to the calling program one of the following entries for each element 

selected. The number of these entries produced is given by item NUM_RTN_ENTRIES 

in the generic part of the function packet. 

The structure for the return entry is defined in element FP$RTN$ELT. See 

Figure 6–3. 

0 RESULT_INDICATOR 

1 

2 ELT_NAME 

3 

4 

5 ELT_VERSION 

6 

7 SEQ_NUM ELT_TYPE aa 

8 ELT_SUBTYPE_NAME 

9 a b c d e f 

10 CREATE_DATE_TIME 

11 

12 TEXT_LOCATION 

13 TEXT_SIZE 

Figure 6–3. The First 14 Words of the Return Entry 

Words 14 and 15 of the return entry depend on the value of ELT_TYPE. Following are 

the possible overlays. 

7830 9796–013 6–17


Possible Overlays for Words 14 and 15 of the Return Entry 

Overlay used when ELT_TYPE = ABS: 

14 j k l m n 

15 NUM_PROG_BANKS NUM_COMMON_BANKS 

Overlay used when ELT_TYPE = OMN: 

14 APPLICATION_VALUE 

15 

Overlay used when ELT_TYPE = REL: 

14 PREAMBLE_SIZE 

15 PREAMBLE_LOCATION 

Overlay used when ELT_TYPE = SYM: 

14 TEXT_TYPE MAX_CYCLE 

15 CURRENT_CYCLE NUM_CYCLES 

Words 8 – 15 are present only when INFO_DETAIL = LONG in the function packet. 


RESULT_INDICATOR 

Indicates whether PCFP successfully completed the operation for this element, and 

provides an explanation if it did not. For the ACQ_ELT_INFO, the value of this item 

is always FP_ERR_NONE (0). 

Data Type: ELMS condition-id 

ELT_NAME 

Indicates the name of the element. 


ELT_VERSION 

Indicates the version of the element. If the element has no version, the item 

contains all spaces. 


6–18 7830 9796–013

SEQ_NUM 


Indicates the sequence number of the element in the table of contents of the 

program file. 

Data Type: integer 

ELT_TYPE 

Indicates the type of the element. 


ABS =1 

OMN = 2 

REL = 3 

SYM = 4 

aa = OMN_SYM_SUBTYPE 

Indicates the subtype of the element. This item is applicable only for an omnibus or 

a symbolic element (ELT_TYPE = OMN or SYM). 


SYM = 0 FLT = 16 GSA = 32 

ELT = 1 PNC = 17 MSG = 33 

ASM = 2 TCL = 18 PRT = 34 

COB = 3 MSM = 19 RPG = 35 

FOR = 4 MSD = 20 ADA = 36 

ALG = 5 MAC = 21 PEER = 37 

MAP = 6 APT = 22 C = 38 

DOC = 7 PGA = 23 FHLL = 39 

SEC = 8 QLP = 24 LINK = 40 

SSG = 9 INL = 25 COM = 41 

APL = 10 DCL = 26 PADS = 42 

BAS = 11 SDL = 27 SSDP = 43 

LSP = 12 FDP = 28 FLDP = 44 

PLS = 13 PSP = 29 ASMP = 64 

PL1 = 14 PAS = 30 COBP = 65 

CTS =15 IPF = 31 FORP = 66 

7830 9796–013 6–19


aa = ABS_SUBTYPE (overlays OMN_SYM_SUBTYPE) 

Indicates the subtype of the element. This item is applicable only for an absolute 

element (ELT_TYPE = ABS). 


ABS = 0 

OM = 1 

SSD = 2 

ZM = 3 

BOM = 17 

The remaining items in the element return entry are present only if the calling program 

set INFO_DETAIL = LONG in the function packet. 

ELT_SUBTYPE_NAME 

Indicates the character mnemonic for the element subtype. This item has a value of 

all spaces when ELT_TYPE = REL. 


a = ELT_DELETED 

Indicates whether the element has been marked deleted. 


b = ELT_IN_ERROR 

Indicates whether the element has been marked in error. 


c = QUARTER_WORD_SENSITIVE 

Indicates whether the element has been marked as quarter-word sensitive. 


d = THIRD_WORD_SENSITIVE 

Indicates whether the element has been marked as third-word sensitive. 


6–20 7830 9796–013

e = ARITH_FAULT_NON_INTERRUPT 


Indicates whether the element has been marked for Arithmetic Fault Noninterrupt 

mode. 


f = ARITH_FAULT_COMPATIBLE 

Indicates whether the element has been marked for Arithmetic Fault Compatibility 

mode. 


CREATE_DATE_TIME 

Indicates the date and time the element was created. 


TEXT_LOCATION 

Indicates the starting word address of the text of the element in the program file. 


TEXT_SIZE 

Indicates the size of the text of the element in words. If the element is a relocatable 

element, the PREAMBLE_SIZE is included in the TEXT_SIZE. If the element text 

size is an illegal value, TEXT_SIZE has a value of -1. 


The following items overlay each other in each element return entry. The items that 

exist in a particular entry depend upon the type of the element (ELT_TYPE) described by 

the entry. The following items exist only when ELT_TYPE = ABS: 

j = DUAL_PSR 

Indicates whether the absolute element requires a dual PSR machine to execute. 


k = ZERO_FILL_SUPPRESS 

Indicates whether the Exec zero-fills uninitialized areas of this absolute element at 

the start of its execution. 


7830 9796–013 6–21


l = NO_START_ADDRESS 

Indicates whether this absolute element has no start address. 


m = REAL_TIME_LOAD 

Indicates whether this element requires real time load when it executes. 


n = BLOCK_SIZE_64 

Indicates whether this absolute element has a block size of 64 words instead of 512 

words. 


NUM_PROG_BANKS 

Indicates the number of program banks contained in the absolute element. 


NUM_COMMON_BANKS 

Indicates the number of common banks referenced by the absolute element. This 

item is applicable only for absolute elements with subtype ABS(0). 


The following item exists only when ELT_TYPE = OMN: 

APPLICATION_VALUE. 

Application dependent value for this omnibus element. 


The following items exist only when ELT_TYPE = REL: 

PREAMBLE_SIZE 

Indicates the size in words of the preamble of the relocatable element. If the 

element preamble size is an illegal value, PREAMBLE_SIZE has a value of -1. 


6–22 7830 9796–013

PREAMBLE_LOCATION 


Indicates the starting word address of the preamble of the relocatable element in the 

program file. 


The following items exist only when ELT_TYPE = SYM: 

TEXT_TYPE 

Indicates whether the symbolic element contains ASCII or Fieldata text. 


ASCII = 1 

Fieldata = 2 

MAX_CYCLES 

Indicates the maximum number of symbolic cycles the element may contain. 

Data Type: unsigned integer range (1 to 63) 

CURRENT_CYCLE 

Indicates the number of the most recent symbolic cycle in the element. 


NUM_CYCLES 


Indicates the actual number of symbolic cycles currently in the element. 


The ACQ_ELT_INFO function works with any work area greater than or equal to the 

minimum size of 1,000 words. The function can work more efficiently with larger work 

area sizes. The actual memory usable by the function varies with the size of the 

program file on which it operates. This function can make effective use of about 200 + 

10*N words, where N is the number of elements (deleted and undeleted) in the program 

file. Thus, a work area size larger than the minimum is useful with a program file 

containing more than 80 elements. The maximum size work area is useful only for a 

program file containing about 2,000 elements or more. 

7830 9796–013 6–23


6.3. Acquire Relocatable Entry Point Information 

(ACQ_REL_EP_INFO) 

The ACQ_REL_EP_INFO function returns information from the relocatable entry point 

table in a program file. (A different function ACQ_OM_EP_INFO returns information 

from the object-module entry point table.) This function can return both undeleted and 

deleted relocatable entry points. 

This function returns the following information about each relocatable entry point it 

selects: 

• Entry point name 

• Sequence number of element containing the entry point 

• Name and version of element containing the entry point (optional) 

• Deletion indicator 

This function can select relocatable entry points based on any combination of the 

following attributes: 


• Name of relocatable element containing the entry point 

• Version of relocatable element containing the entry point 

Each attribute for which the calling program supplies a value further restricts the set of 

entry points this function selects. The calling program may supply values for as few or 

as many of these attributes as it requires. If the calling program supplies no values for 

any attributes, all relocatable entry points in the program file are selected. 


• Select the undeleted entry points, deleted entry points, or both. 

• Limit the number of relocatable entry points acquired to a specified maximum. If 

more entry points than the maximum qualify, PCFP does not return the excess to 

the calling program. 

• For each entry point selected, either return or do not the name and version of the 

element containing the entry point. 


The ACQ_REL_EP_INFO function has the following parameters, each of which is 





• Work Area 

6–24 7830 9796–013



The structure of the ACQ_REL_EP_INFO function packet is defined in element 

FP$ACQRELEP. See Figure 6–4. 

GENERIC PART 


0 MAX_COUNT INFO_DETAIL 

1 DELETION 

2 

3 EP_NAME 

4 

5 

6 ELT_NAME 

7 

8 

9 ELT_VERSION 

10 



MAX_COUNT 

Figure 6–4. ACQ_REL_EP_INFO Function Packet Items 

Indicates the maximum number of entry points this function acquires. A value of 

zero indicates no maximum. 


INFO_DETAIL 


SHORT = 0 

Indicates that the following information only is to be returned for each entry 

point: entry point name, sequence number of element containing the entry point, 

and deletion indicator. 

7830 9796–013 6–25


LONG = 1 

DELETION 

Indicates that the name and version of the element containing the entry point 

are to be returned, in addition to the information listed above. 


UNDELETED = 0 

Indicates that this function selects only undeleted entry points. 

DELETED = 1 

Indicates that this function selects only deleted entry points. 

BOTH = 2 

EP_NAME 

Indicates that this function selects entry points whether or not they are deleted. 

Indicates the name or pattern of the name of the relocatable entry points that this 

function selects. The value the calling program supplies for this item may contain 

the question mark ( ? ) and the asterisk ( * ) wild-card characters as described in 2.6. 

A null value indicates the entry points are selected without regard to their names. 


ELT_NAME 

Indicates the name or pattern of the name of the relocatable elements containing the 

entry points that this function selects. The value that the calling program selects for 

this item may contain the question mark ( ? ) and the asterisk ( * ) wild-card 

characters as described in 2.6. A null value indicates the entry points are selected 

without regard to the name of the element containing them. 


ELT_VERSION 

Indicates the version or pattern of the version of the relocatable elements containing 

the entry points that this function selects. The value the calling program supplies for 

this item may contain the question mark ( ? ) and the asterisk ( * ) wild-card 

characters as described in 2.6. A null value indicates the entry points are selected 

without regard to the version of the element containing them. 


6–26 7830 9796–013

NUM_SELECTED 

Indicates how many entry points the function selected. 








One of the following entries is returned for each relocatable entry point the function 

selects. The number of these entries produced is given by item NUM_RTN_ENTRIES in 

the function packet. This return entry structure is defined in element FP$RTN$RELEP. 


0 a SEQ_NUM 

1 

2 EP_NAME 

3 

4 

5 ELT_NAME 

6 

7 

8 ELT_VERSION 

9 

Figure 6–5. ACQ_REL_EP_INFO Return Entry Items 

Items ELT_NAME and ELT_VERSION are present only when the calling program set 

INFO_DETAIL = LONG in the function packet. 


a = DELETE_FLAG 

Indicates whether the entry point is deleted. 


7830 9796–013 6–27


SEQ_NUM 

Indicates the sequence number of the element that contains the entry point. 


EP_NAME 

Indicates the name of the entry point. 


The following items are included in the long form only. 

ELT_NAME 

Indicates the name of the relocatable element that contains the entry point. 


ELT_VERSION 


Indicates the version of the relocatable element that contains the entry point. 


The ACQ_REL_EP_INFO function works with any work area greater than or equal to the 

minimum size of 2,000 words. This function works more efficiently with larger work 


program file. In approximate terms, this function can make efficient use of 400 + 4*EP 

+ 10*N words, where EP is the number of relocatable entry points and N is the number 

of elements (deleted and undeleted) in the program file. Thus, a work area size larger 

than the minimum is useful, for example, with a program file containing more than 350 

relocatable entry points in 20 elements. For most situations, the minimum work area 

size of 2,000 words gives acceptable performance. 

6–28 7830 9796–013

6.4. Acquire Object Module Entry Point 

Information (ACQ_OM_EP_INFO) 


The ACQ_OM_EP_INFO function returns information from the object module entry point 

table in a program file. (A different function ACQ_REL_EP_INFO returns information 

from the relocatable entry point table.) 

This function returns the following information about each object-module entry point it 

selects: 

• Entry point name (Although object-module entry point names can be any length, this 

function returns only the first 32 characters.) 

• Length of full entry point name 

• Sequence number of object-module absolute element containing the entry point 

• Index of the entry point in the object-module absolute element that contains it 

• Indication of whether or not the entry point has been prepped 

• Date and time the entry point was created 

• The entry point type (common-block, code, constant, data, or fixed-gate) 

• Standard calling sequence conformance of the entry point (none, loose, or strict) 

• Text type of the entry point (ASCII or Kanji) 

• Name and version of the object-module absolute element containing the entry point 

(optional) 

This function can select object module entry points based on any combination of the 

following attributes: 


• Name of element containing the entry point 

• Version of element containing the entry point 

• Entry point type 

• Standard calling sequence conformance of the entry point 

• Text-type of the entry point 

• Date and time the entry point was created 


entry points that this function selects. The calling program may supply values for as few 

or as many of these attributes as it requires. If the calling program supplies no values for 

any attributes, all object-module entry points in the program file are selected. 

7830 9796–013 6–29



• Limit the number of object-module entry points acquired to a specified maximum. If 

more entry points than the maximum qualify, PCFP does not return the excess to 


• For each entry point selected, either return the name and version of the element 

containing the entry point, or not. 


The ACQ_OM_EP_INFO function has the following parameters, each of which is 





• Work Area 

6–30 7830 9796–013



The structure of the ACQ_OM_EP_INFO function packet is defined in element 

FP$ACQOMEP. See Figure 6–6. 

GENERIC PART 



1 a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a 

2 TEXT_TYPE SCF_CONFORMANCE 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

… 

21 

22 

… 

29 

MIN_DATE_TIME 

MAX_DATE_TIME 

ELT_NAME 

ELT_VERSION 

EP_NAME 


Figure 6–6. ACQ_OM_EP_INFO Function Packet Items 

7830 9796–013 6–31 

…



MAX_COUNT 

Indicates the maximum number of entry points this function returns. A value of zero 

indicates no maximum. 


INFO_DETAIL 


SHORT = 0 

Indicates that PCFP does not return the name and version of the element 

containing each entry point to the calling program. 

LONG = 1 

Indicates that PCFP returns the name and version of the element containing 

each entry point to the calling program. 

a = EP_TYPE array (0:35) 

Indicates the types of entry points this function selects. Each item in this array 

occupies a single bit. If the calling program sets any entries in this array to TRUE (1), 

this function selects only object-module entry points with a type corresponding to a 

TRUE item. If the calling program sets no item in the array to TRUE, the function 

selects object-module entry points regardless of type. 


TEXT_TYPE 

Indicates the text type of the object module entry points that the function selects. 



Causes selection of entry points regardless of text type. 

ASCII = 1 

Limits entry points selected to those with ASCII names. 

Kanji = 3 

Limits entry points selected to those with Kanji names. 

6–32 7830 9796–013

SCS_CONFORMANCE 


Indicates the standard calling sequence conformance of the object-module entry 

points that the function selects. 



Causes selection of entry points regardless of SCS conformance. 

NONE = 1 

Limits entry points selected to those with no conformance. 

LOOSE = 16 

Limits entry points selected to those with loose conformance. 

STRICT = 17 

Limits entry points selected to those with strict conformance. 

MIN_DATE_TIME 

Indicates whether PCFP selects entry points with or without regard to a minimum 

date and time of creation. If this item is nonzero, PCFP selects only object-module 

entry points with a date and time of creation greater than or equal to that specified. 

If this item is zero, PCFP selects entry points without regard to a minimum date and 

time. 


MAX_DATE_TIME 

Indicates whether PCFP selects entry points with or without regard to a maximum 

date and time of creation. If this item is not zero, PCFP selects object-module entry 

points with a date and time less than or equal to that specified. If this item is zero, 

PCFP selects entry points without regard to a maximum date and time. 


ELT_NAME 

Indicates the name or pattern of the name of the object-module absolute elements 

containing the entry points that this function selects. The value the calling program 

supplies for this item may contain the question mark ( ? ) and the asterisk ( * ) 

wild-card characters as described in 2.6. A null value indicates the entry points are 

selected without regard to the name of the element containing them. 


7830 9796–013 6–33


ELT_VERSION 

Indicates the version or pattern of the version of the object-module absolute 

elements containing the entry points that this function selects. The value the calling 

program supplies for this item may contain the question mark ( ? ) and the asterisk 

( * ) wild-card characters as described in 2.6. A null value indicates the entry points 

are selected without regard to the version of the element containing them. 


EP_NAME 

Indicates the name or pattern of the name of the object-module entry points that this 

function selects. This item is case sensitive: uppercase and lowercase letters are 

not equivalent. The value the calling program supplies for this item may contain the 

question mark ( ? ) and the asterisk ( * ) wild-card characters as described in 2.6. A 

null value indicates the entry points are selected without regard to their names. If 

the calling program supplies a nonnull value for this item, it must also set 

TEXT_TYPE = ASCII. Object-module entry point names greater than 32 characters 

cannot match any specified EP_NAME, even if wild-card characters are used. 


NUM_SELECTED 

Indicates how many entry points the function selected. 






6–34 7830 9796–013



One of the following entries is returned for each object-module entry point the 

ACQ_OM_EP_INFO function selects. The number of these entries produced is given by 

item NUM_RTN_ENTRIES in the function packet. This return entry structure is defined 

in element FP$RTN$OMEP. See Figure 6–7. 

0 SEQ_NUM EP_INDEX 

1 CREATE_DATE_TIME 

2 

3 EP_TYPE b c 

4 TEXT_TYPE PREPPED EP_NAME_LENGTH 

5 

6 

.. EP_NAME 

21 

22 

23 ELT_NAME 

24 

25 

26 ELT_VERSION 

27 

Figure 6–7. ACQ_OM_EP_INFO Return Entry Items 




SEQ_NUM 

Indicates the sequence number of the element that contains the entry point. 


EP_INDEX 

Indicates the index of the entry point in the object-module element that contains it. 


7830 9796–013 6–35


CREATE_DATE_TIME 

Indicates the date and time that the entry point was created. 


EP_TYPE 

Indicates the definition type of the entry point. 


UNKNOWN = 0 

COMMON_BLOCK_EP = 16 

CODE_EP = 17 

CONSTANT_EP = 18 

DATA_EP = 19 

FIXED_GATE_EP = 20 

b = VISIBILITY 

Indicates whether the entry point is internal or external. (Currently this function only 

returns entry points with VISIBILITY = EXT.) 


EXT = 16 

INT = 17 

c = SCS_CONFORMANCE 

Indicates the standard calling sequence conformance of the entry point. 


UNDEFINED = 0 

NONE = 1 

LOOSE = 16 

STRICT = 17 

TEXT_TYPE 

Indicates the text type of the entry point name. 


ASCII = 1 

Kanji = 3 

6–36 7830 9796–013

PREPPED 


Indicates whether the object module entry point has been prepped. 


UNPREPPED = 0 

PREPPED = 1 

EP_NAME_LENGTH 

Contains the complete length of the entry point name in characters (ASCII or Kanji). 


EP_NAME 

Contains up to the first 32 characters of the entry point name. This item is case 

sensitive: uppercase and lowercase letters are not equivalent in object module entry 

point names. If EP_NAME_LENGTH is greater than 32 characters, only the first 32 

characters are returned. The type of characters returned is indicated by TEXT_TYPE. 


(For the C language, this item is a union containing character arrays named ASCII and 

KANJI.) 

The following items are included in the long form only: 

ELT_NAME 

Indicates the name of the object-module absolute element that contains the entry 

point. 


ELT_VERSION 

Indicates the version of the object-module absolute element that contains the entry 

point. 


7830 9796–013 6–37



The ACQ_OM_EP_INFO function works with any work area greater than or equal to the 



program file. In approximate terms, this function can make efficient use of 200 + 28 * 

EP + 10 * N words, where EP is the number of object-module entry points and N is the 

number of elements (deleted and undeleted) in the program file. Thus, a work area size 

larger than the minimum is useful, for example, with a program file containing more than 

50 object-module entry points in 40 elements. For most situations, the minimum work 

area size of 2,000 words gives acceptable performance. 



function, where the minimum relative address is MIN_DATA_ADDR_WITH_LINK and the 

maximum relative address is MAX_DATA_ADDR, as contained in the copy/include 


6–38 7830 9796–013

6.5. Acquire Procedure Information 

(ACQ_PROC_INFO) 


The ACQ_PROC_INFO function returns information from a specified procedure table in a 

program file. Any of the procedure tables in a program file can be handled by this 

function. (There are three procedure tables: assembler, COBOL, and FORTRAN-PLUS.) 

For each procedure selected, the ACQ_PROC_INFO function returns the following 

information: 

• Procedure name 

• Sequence number of the symbolic element containing the procedure 

• Name and version of the symbolic element containing the procedure (optional) 

• Mass-storage address of the start of the procedure in the program file 

• Text type of procedure (ASCII or Fieldata) 

• Deletion indicator 

This function can select procedures based on any combination of the following 

attributes: 

• Procedure name 

• Name of symbolic element containing the procedure 

• Version of symbolic element containing the procedure 


entry points that this function selects. The calling program may supply values for as few 

or as many of these attributes as it requires. If the calling program specifies no values 

for any attributes, all procedures in the table are specified by the calling program. 


• Acquire information from the assembler procedure table, the COBOL procedure 

table, or the FORTRAN-PLUS procedure table. 

• Select undeleted procedures, deleted procedures, or both. 

• Limit the number of procedure entries returned to a specified maximum. If more 

procedures than the maximum qualify, PCFP does not return the excess to the 



The ACQ_PROC_INFO function has the following parameters, each of which is 





• Work Area 

7830 9796–013 6–39



The structure for ACQ_PROC_INFO function packet is defined in element 

FP$ACQPROC. See Figure 6–8. 

GENERIC PART 


0 DELETION PROC_TABLE 


2 PROC_NAME 

.. . . . 

8 

9 PROC_NAME 

10 

11 ELT_NAME 

12 

13 


15 



DELETION 

Figure 6–8. ACQ_PROC_INFO Function Packet Items 


UNDELETED = 0 

Indicates that this function selects only undeleted procedures. 

DELETED = 1 

Indicates that this function selects only deleted procedures. 

BOTH = 2 

Indicates that this function selects procedures whether or not they are deleted. 

6–40 7830 9796–013

PROC_TABLE 


Indicates the procedure table from which the function retrieves procedures. 


MASM_PROC = 2 

COBOL_PROC = 3 

FTN_PLS_PROC = 4 

MAX_COUNT 

Indicates the maximum number of procedure entries this function acquires. A value 

of zero indicates no maximum. 


INFO_DETAIL 


SHORT = 0 

Indicates that PCFP does not return the name and version of the element 

containing each procedure. 

LONG = 1 

PROC_NAME 

Indicates that PCFP returns the name and version of the element containing 

each procedure. 

Indicates the name or the pattern of the name of the procedures that this function 

selects. The value the calling program supplies for this item may contain the 

question mark ( ? ) and asterisk ( * ) wild-card characters as described in 2.6. A null 

value indicates that procedures are selected without regard to their names. The 

value the calling program supplies for this item must not be longer than 12 

characters when PROC_TABLE = MASM_PROC or FTN_PLS_PROC. 


ELT_NAME 

Indicates the name or the pattern of the name of the elements containing the 

procedures that this function selects. The value the calling program supplies for this 

item may contain the question mark ( ? ) and the asterisk ( * ) wild-card characters as 

described in 2.6. A null value indicates that procedures are selected without regard 

to the name of the element containing them. 


7830 9796–013 6–41


ELT_VERSION 

Indicates the version or the pattern of the version of the elements containing the 

procedures that this function selects. The value the calling program supplies for this 

item may contain the question mark ( ? ) and the asterisk ( * ) wild-card characters as 

described in 2.6. A null value indicates that procedures are selected without regard 

to the version of the element containing them. 


NUM_SELECTED 

Indicates how many procedures the function selected. 






6.5.4. Return Entry for MASM, FORTRAN, and PLUS 

Procedures 

This function returns one of two information structures depending on the value of 

PROC_TABLE in the function packet. It is important that the structure definition you 

include in your program matches the structure requested from PCFP in the function 

packet. 

When the calling program sets PROC_TABLE = MASM_PROC or FTN_PLS_PROC, this 

function returns one of the following entries for each procedure selected (see 

Figure 6–9). The number of these entries the function produces is given by the item 

NUM_RTN_ENTRIES in the function packet. 

6–42 7830 9796–013

This return-entry structure is defined in element FP$RTN$PROC. 


0 a TEXT_TYPE SEQ_NUM 

1 PROC_LOCATION 

2 

3 PROC_NAME 

4 

5 

6 ELT_NAME 

7 

8 

9 ELT_VERSION 

10 

Figure 6–9. ACQ_PROC_INFO Return Entry Structure When 

PROC_TABLE = MASM_PROC or FTN_PLS_PROC 

Items ELT_NAME and ELT_VERSION are returned only when the calling program set 




Indicates whether the procedure is deleted. 


TEXT_TYPE 

Indicates whether the procedure images are ASCII or Fieldata. 


ASCII = 1 

Fieldata = 2 

SEQ_NUM 

Indicates the sequence number of the element that contains the procedure. 


7830 9796–013 6–43


PROC_LOCATION 

Indicates the word address of the start of the procedure within the program file. 


PROC_NAME 

Indicates the name of the procedure. 


The following items are included only when INFO_DETAIL = LONG in the function 

packet. 

ELT_NAME 

Indicates the name of the element that contains the procedure. 


ELT_VERSION 

Indicates the version of the element that contains the procedure. 


6.5.5. Return Entry for COBOL Procedures 

This function returns one of two information structures depending on the value of 

PROC_TABLE in the function packet. It is important that the structure definition you 

include in your program matches the structure requested from PCFP in the function 

packet. 

When the calling program sets PROC_TABLE = COBOL_PROC, this function returns one 

of the following entries for each procedure selected (see Figure 6–10). The number of 

these entries the function produced is given by the item NUM_RTN_ENTRIES in the 

function packet. 

This return entry structure is defined in element FP$RTN$PROC. 

6–44 7830 9796–013


0 a TEXT_TYPE SEQ_NUM 

1 PROC_LOCATION 

2 PROC_NAME 

. . . . . 

8 

9 PROC_NAME 

10 

11 ELT_NAME 

12 

13 


15 

Figure 6–10. ACQ_PROC_INFO Return Information Structure When 

PROC_TABLE = COBOL PROC 





Indicates whether the procedure is deleted. 


TEXT_TYPE 

Indicates whether the procedure images are ASCII or Fieldata. 


ASCII = 1 

Fieldata = 2 

SEQ_NUM 

Indicates the sequence number of the element that contains the procedure. 


7830 9796–013 6–45


PROC_LOCATION 

Indicates the word address of the start of the procedure within the program file. 


PROC_NAME 

Indicates the name of the procedure. 


The following items are included only when INFO_DETAIL = LONG in the function 

packet. 

ELT_NAME 

Indicates the name of the element that contains the procedure. 


ELT_VERSION 


Indicates the version of the element that contains the procedure. 


The ACQ_PROC_INFO function works with any work area greater than or equal to the 



program file. In approximate terms, this function can make efficient use of 400 + 8*P + 

10*N words, where P is the number of procedures (deleted and undeleted) and N is the 

number of elements (deleted and undeleted) in the program file. Thus, a work area size 

larger than the minimum is useful, for example, with a program file containing 125 

procedures in 60 elements. For most situations, the minimum work area size of 2,000 

words gives acceptable performance. 

6–46 7830 9796–013

Section 7 

Copying Program File Elements 

This section describes the following five functions that copy an element from or to a 

program file. 

• Copy Elements (COPY_ELT) 

• Copy Symbolic Element to RAF (COPY_SYM_ELT_RAF) 

• Copy RAF to Symbolic Element (COPY_RAF_SYM_ELT) 

• Copy Omnibus Element to RAF (COPY_OMN_ELT_RAF) 

• Copy RAF to Omnibus Element (COPY_RAF_OMN_ELT) 

7.1. Copy Elements (COPY_ELT) 

The COPY_ELT function copies one or more elements from one program file to another 

program file. The copied elements have the same type, subtype, and ASCII/Fieldata 

indicator in the destination file they had in the source file. 

This function corresponds to the FURPUR @COPY command with some combination of 

the A, O, P, R, and S options. 

You can select the elements you want copied based on name, version, type, subtype, or 

some combination of these. You can specify part of a name and/or version, as described 

in 2.6. You cannot select deleted elements. 

The COPY_ELT function provides the following options: 

• Require PCFP to assign the destination file exclusively or not. 

• Initialize an empty destination file as a PF, LPF, standard LEPF, large LEPF, or as the 

same program file type as the source file. 

• Have each element retain its original name and version after it is copied, or give each 

element a new name and/or version as specified by the calling program. If a new 

name or version is specified, it may include wild-card characters indicating that the 

corresponding characters from the original name or version are to be retained. See 

2.6 for details. 

• If an element to be copied has the same name, version, and type as an element 

already in the destination file, do one of the following: 

− Delete the original and complete the copy. 

− Retain the original and do not complete the copy. 

7830 9796–013 7–1


− Delete the original and complete the copy only if the element being copied has a 

later date and time of creation. 

• For each symbolic element, copy either all symbolic cycles or only a single specified 

symbolic cycle. In the latter case, you can specify the cycle number as either an 

absolute number or a number relative to the latest cycle. 

• Either retain the old date and time of creation for each element copied or assign the 

current date and time into those fields. 

• Return name, version, type, and result indicator for 

− Each element that was selected and successfully copied 

− Each element that was selected but not copied 

− Each element that was selected, whether it was copied or not 

− No elements 

In all cases, the COPY_ELT function returns the number of elements it selected for 

copying, the number it successfully copied, and the number it did not copy. 

When this function copies one or more relocatable elements into the destination 

program file, it removes any relocatable entry point table that previously existed in the 

program file. However, when this function copies one or more object module absolute 

elements into a program file, it does not remove any existing object module entry point 

tables. 

When this function copies one or more procedure symbolic elements to the destination 

file and all symbolic cycles are specified, it also copies all procedure table entries 

associated with those elements. 

When this function causes one or more procedure symbolic elements to be deleted from 

the destination file, it also deletes any procedure entries associated with those 

elements. 


The COPY_ELT function has the following parameters, each of which is described in the 






• Work Area 

7–2 7830 9796–013


0 

1 

2 

3 

4 

5 

10 

11 

12 

13 

14 

15 

6 a b c d 


The structure of the function packet for COPY_ELT is defined in element FP$CPYELT. 


GENERIC PART 


ELT_NAME 

ELT_VERSION 



9 f f f f f f f f f f f f f f f f f f INIT_DEST_FILE 

DEST_ELT_NAME 

DEST_ELT_VERSION 

16 g h i ON_CONFLICT 

17 CYCLE_TYPE CYCLE_NUM 

18 INFO_TO_RETURN INFO_DETAIL 


20 NUM_SUCCESSFUL 

21 NUM_FAILED 

Figure 7–1. COPY_ELT Function Packet Items 

7830 9796–013 7–3



ELT_NAME 

Indicates name or pattern of the name of the elements this function copies. The 

value the calling program supplies for this item may contain the question mark ( ? ) 

and asterisk ( * ) wild-card characters as described in 2.6. A null value indicates the 

elements are to be copied without regard to element name. 


ELT_VERSION 

Indicates version or pattern of the version of the elements this function copies. The 


and asterisk ( * ) wild-card characters as described in 2.6. A null value indicates the 

elements are to be copied without regard to version. 


a = ABS_TYPE 

Indicates whether absolute elements are to be copied. 


b = OMN_TYPE 

Indicates whether omnibus elements are to be copied. 


c = REL_TYPE 

Indicates whether relocatable elements are to be copied. 


d = SYM_TYPE 

Indicates whether symbolic elements are to be copied. 


If the calling program sets items ABS_TYPE, OMN_TYPE, REL_TYPE, and 

SYM_TYPE all to FALSE or all to TRUE, elements are copied regardless of their type. 

7–4 7830 9796–013



Indicates which subtypes of omnibus and symbolic elements this function copies. 

Each item in this array occupies a single bit. If the calling program sets any entries in 

this array to TRUE (1), only omnibus and symbolic elements that have a numeric 

subtype corresponding to a TRUE entry are copied. If the calling program sets no 

item in the array to TRUE, this function copies omnibus and symbolic elements 

regardless of subtype. This item applies only to symbolic and omnibus elements and 

does not affect the selection of elements of other types. 



Indicates which subtypes of absolute elements this function copies. Each item in 

this array occupies a single bit. If the calling program sets any entries in this array to 

TRUE (1), only absolute elements that have a numeric subtype corresponding to a 

TRUE entry are copied. If the calling program sets no item in the array to TRUE, this 

function copies absolute elements regardless of subtype. This item applies only to 

absolute elements and does not affect the selection of elements of other types. 


INIT_DEST_FILE 

Indicates how PCFP should initialize an empty destination file. 


NONE = 0 

PF = 1 

This value must be specified if the destination file is not initially empty. If the 

destination file is empty, it will be initialized as a standard program file (PF). 

LPF = 2 

Initialize the destination file as a standard program file (PF). 

Initialize the destination file as a large program file (LPF). 


Initialize the destination file as a standard capacity, large element program file 

(standard LEPF). 


Initialize the destination file as a large capacity, large element program file (large 

LEPF). 

7830 9796–013 7–5


SOURCE_FILE_TYPE = 5 

Initialize the destination file as the same program file type as the source file. 

For values other than NONE, the destination file must be empty. Files are empty 

when initially created with @ASG or @CAT and when erased with the PCFP 


DEST_ELT_NAME 

Indicates the name PCFP gives to the copied element in the destination file. The 


wild-card character. PCFP replaces each question mark by the corresponding 

character in the original element name. If this value is null, the elements PCFP 

copies retain their original names. 



Indicates the version PCFP gives to the copied element in the destination file. The 


wild-card character. Each question mark is replaced by the corresponding character 

in the original element version. If this value is null, the elements PCFP copies retain 

their original versions. 


g = EXCLUSIVE_ASSIGN 

Indicates whether or not PCFP must assign the destination file exclusively. 


h = NEW_DATE_TIME 

Indicates whether each element being copied retains its old date and time of 

creation or changes to the date and time that the copy is performed. 


i = COPY_CURRENT_CYCLE 

Indicates how the text of symbolic elements other than procedure elements is 

copied, when the text has an SDF type of general symbolic. When TRUE, only 

non-deleted records are copied to the destination file where they are identified as 

being added at cycle 0. When FALSE or when the element is a procedure element 

or when the SDF type is other than general symbolic, the copy is performed as 

described for CYCLE_TYPE and CYCLE_NUM. 


7–6 7830 9796–013

ON_CONFLICT 


Indicates what action PCFP takes for any element it attempts to copy that has the 

same name, version, and type as an element already in the destination file. 


DO_NOT_COPY = 0 

Indicates that PCFP not copy the element. 

DELETE_ORIGINAL = 1 

Indicates that PCFP delete the existing element with that name, version, and 

type from the destination file, and complete copying the file. 

COPY_IF_NEWER = 2 

CYCLE_TYPE 

Indicates that PCFP delete the existing element from the destination file and 

complete copying the element only if the date and time of the element being 

copied is later than that of the element already in the destination file. 

Indicates if CYCLE_NUM contains an absolute element-cycle value, a relative 

element-cycle value, or no element-cycle value. This item and CYCLE_NUM affect 

only the copying of symbolic elements. 



Indicates that PCFP copies all cycles of the symbolic elements that it selects. If 

this element is a procedure symbolic element, UNSPECIFIED must be selected 

if the associated procedure table entries are to be copied to the destination file. 

ABS = 1 

Indicates that for each symbolic element it selects PCFP copies only the specific 

absolute symbolic cycle indicated by CYCLE_NUM. 

REL = 2 

Indicates that for each symbolic element it selects PCFP copies only the specific 

relative symbolic cycle indicated by CYCLE_NUM. 

7830 9796–013 7–7


CYCLE_NUM 

Indicates the specific cycle that PCFP copies for symbolic elements. If the calling 

program sets CYCLE_TYPE = UNSPECIFIED, it must set this item to 0. If the calling 

program sets CYCLE_TYPE = ABS, it must set this item to a value between 0 and 62 

inclusive. If the calling program sets CYCLE_TYPE = REL, it must set this item to a 

value between -62 and 0 inclusive. If a symbolic element PCFP selects for copying 

does not contain the cycle specified here, PCFP does not copy that element. 


INFO_TO_RETURN 

Indicates which elements selected by PCFP have individual information returned to 



NONE = 0 

Indicates that PCFP returns individual information for no elements. 

ERROR_ONLY = 1 

Indicates that PCFP returns individual information only for each element it 

selected but did not copy. 

NONERROR_ONLY = 2 

Indicates that PCFP returns individual information for each element that it 

selected and copied successfully. 

ALL_INFO = 3 

INFO_DETAIL 

Indicates that PCFP returns individual information for each element it selected, 

whether or not it was copied. 

For each individual element for which PCFP returns information, indicates what parts 

of the element information PCFP returns. PCFP ignores this item if the calling 

program set INFO_TO_RETURN = NONE. 


SHORT = 0 

Indicates that for each element that has return information, PCFP returns only 

the following items: RESULT_INDICATOR, ELT_NAME, ELT_VERSION, 

ELT_TYPE, ELT_SUBTYPE, ELT_SEQ_NUM. 

7–8 7830 9796–013

LONG = 1 


Indicates that PCFP returns all information described in 6.2.4 for each element. 

SUMMARY = 3 

Indicates that instead of returning individual information for each element, PCFP 

summarizes the information and returns it in a single summary entry, as 

described in 7.1.5. 

NUM_SELECTED 

Indicates the number of source file elements PCFP found that were not deleted and 

that matched function packet specifications for element name (ELT_NAME), element 

version (ELT_VERSION), element type (ABS_TYPE, OMN_TYPE, REL_TYPE or 

SYM_TYPE) and element subtype (OMN_SYM_SUBTYPE or ABS_SUBTYPE). 


NUM_SUCCESSFUL 

Indicates the number of elements PCFP actually copied. 


NUM_FAILED 

Indicates the number of source file elements selected by PCFP that were not copied 

to the destination file. The elements were not copied because the masking 

specified in destination element name (DEST_ELT_NAME) or destination version 

name (DEST_ELT_VERSION) created an illegal name, because the same element 

name, element version and element type already existed in the destination file and 

the ON_CONFLICT specification did not allow element deletion, or because the 

element did not match symbolic element cycle number specifications (CYCLE_TYPE 

and CYCLE_NUM). If the calling program requested return of error information, the 

reason that the element was not copied to the destination file is indicated by 

RESULT_INDICATOR in the return entry. 

Serious errors that cause termination of the COPY_ELT function are not counted in 

this item. These errors are reported in the generic part of the function packet, as 


When the function completes successfully, NUM_SELECTED is equal to the sum of 

NUM_SUCCESSFUL and NUM_FAILED. When the function terminates because of 

an error during an element copy, NUM_SELECTED can be one greater than the sum 

of NUM_SUCCESSFUL and NUM_FAILED. 


7830 9796–013 7–9



The source file identifier parameter names the file from which elements are copied. The 

named file must be a program file on sector-addressable mass storage for which the 



The destination file identifier parameter names the file to which elements are copied. 

The named file must initially be either a program file or empty. It must reside on 

sector-addressable mass storage, and the calling program must have both read and write 

privileges for the file. See 2.3 for a description of this parameter. 


When the function packet item INFO_DETAIL is set to SHORT or LONG, PCFP returns 

one entry for each element indicated by the function packet item INFO_TO_RETURN. 

See 6.2.4 for a description of these entries. 

For those elements that PCFP selected and was able to copy, PCFP sets the item 

RESULT_INDICATOR in the return entry to one of the following values: 

FP_ERR_NONE 

Indicates that PCFP copied the element successfully with no complications. 

FP_INFO_PROC_TOC_FULL 

Indicates that PCFP copied the element successfully, but was unable to insert some 

or all of the procedure entries associated with the element because the procedure 

table in the destination file is full. When this error is detected, the function is 

terminated. 

FP_INFO_PROC_TBL_ERR 

Indicates that PCFP copied the element successfully, but was unable to process 

some or all of the procedure entries associated with the element. When this error is 

detected, the function is terminated. 

For those elements that PCFP selected but was not able to copy, PCFP sets the item 

RESULT_INDICATOR to one of the following values: 

FP_WARN_ELT_CONFLICT 

Indicates that PCFP was not able to copy the element because the destination file 

already contains an element of the same type that has a name and version matching 

the name and version of the destination element. This value is returned only if the 

calling program set ON_CONFLICT = DO_NOT_COPY in the function packet. 

7–10 7830 9796–013

FP_WARN_ELT_NOT_NEWER 


Indicates that PCFP was not able to copy the element because the destination file 

contains an element with the same name, version, and type, but with a date and 

time of creation that is more recent. This value is returned only if the calling program 

set ON_CONFLICT = COPY_IF_NEWER in the function packet. 

FP_WARN_NONEXISTENT_SYM_CYCLE 

Indicates that PCFP was not able to copy the symbolic element because the 

symbolic cycle specified by the calling program does not exist. 

FP_WARN_BAD_ELT_NAME 

Indicates that PCFP was not able to copy the element because the new name 

generated for it contains an embedded space. 

FP_WARN_BAD_ELT_VERSION 

Indicates that PCFP was not able to copy the element because the new version 

generated for it contains an embedded space. 

When the function packet item INFO_DETAIL is set to SUMMARY, PCFP returns a 

single entry summarizing the copy operations for elements indicated by the function 

packet item INFO_TO_RETURN. The item NUM_RTN_ENTRIES in the Return 

Information part of the function packet is set to 1. 

The structure for the return entry is defined in element FP$RTN$ELT. See Figure 7–2. 

0 TEXT_SIZE 

1 NUM_ELTS NUM_MASM_PROCS 

2 NUM_COBOL_PROCS NUM_FTN_PLS_PROCS 

3 NUM_REL_EPS NUM_OM_EPS 




TEXT_SIZE 

Figure 7–2. Summary Return Entry 

Indicates the total size of the text in words. 

Data type: integer 

NUM_ELTS 

Indicates the total number of elements of all types. 

7830 9796–013 7–11



NUM_MASM_PROCS 

Indicates the total number of MASM procedures associated with symbolic elements 

with subtype ASMP (64). 


NUM_COBOL_PROCS 

Indicates the total number of COBOL procedures associated with symbolic elements 

with subtype COBP (65). 


NUM_FTN_PLS_PROCS 

Indicates the sum of the number of FORTRAN procedures associated with symbolic 

elements with subtype FORP (66) and the number of PLUS procedures associated 

with symbolic elements with subtype PSP (29). 


NUM_REL_EPS 

Indicates the total number of relocatable entry points associated with relocatable 

elements. This item will be zero for COPY_ELT. 


NUM_OM_EPS 

Indicates the total number of object module entry points associated with object 

module absolute elements. This item will be zero for COPY_ELT. 


NUM_ABS_ELTS 

Indicates the total number of absolute elements. 


NUM_OMN_ELTS 

Indicates the total number of omnibus elements. 


7–12 7830 9796–013

NUM_REL_ELTS 

Indicates the total number of relocatable elements. 


NUM_SYM_ELTS 

Indicates the total number of symbolic elements. 




The COPY_ELT function works with any work area greater than or equal to the minimum 

size of 2,000 words. In many situations, this function works more efficiently with a 

larger work area size. The actual memory used by this function varies with the size of 

the program files it operates on, the number of elements it copies, and the text size of 

the largest element it copies. In approximate terms, the word size of the work area 

usable by the function is usually given by 125 + S + D + I + C, where 

S The source file buffer size. S can be approximated as 252 + (10 * J), where J is 

the number of deleted and undeleted elements in the source file. Acceptable 

performance can usually be achieved with the minimum size source file buffer 

(252 words). 

D The destination file buffer size. D can be approximated as 252 + (10 * (K + L)), 

where K is the initial number of deleted and undeleted elements in the destination 

file and L is the number of elements to copy from the source file to the 

destination file. Use the recommended size destination file buffer for optimum 

performance. 

I The input/output buffer size. I can be approximated as the smaller of 65,520 and 

M, where M is the size in words of the largest element to copy. The minimum 

size input/output buffer is 896 words. Acceptable performance can usually be 

achieved with a buffer size of four 1,792-word tracks (7,168 words). 

C The procedure table copy buffer size. C can be approximated as 3 + (3 * N), 

where N is the number of procedure elements to copy from the source file to the 

destination file. Use the recommended size procedure table copy buffer for 

optimum performance. If there are over 50 procedure elements to copy, at least 

150 words must be provided for this buffer. 

As described in 2.4.1, the total work area size plus the return area size cannot exceed 

approximately 238,000 words. 

For optimum performance of this function, ensure that the work area recommended for 

D and I is available. Sufficient work area for these two buffers is the most important 

factor in achieving optimum performance. 

7830 9796–013 7–13


The maximum defined work area size of 74,000 words should provide adequate 

performance for nearly all combinations of source and destination file sizes. For some 

extremely large files, performance may be improved further by providing a work area 

size that is larger than the defined maximum, as indicated by the work area formula. 

When the maximum possible work area size (about 238,000) is specified and return area 

size is specified as zero, there is sufficient work area available to efficiently create a 

destination large program file of approximately 23,000 elements. This is less than the 

design maximum for large program files of 26,146 elements. The efficiency of copy 

operations decreases very significantly as the number of elements increases from 

approximately 23,000 toward the design maximum of 26,146. Likewise, for a 

destination file with approximately 23,000 elements, the efficiency of copy operations 

decreases significantly as the specified work area size decreases from the maximum 

possible size. 

7.2. Copy Symbolic Element to RAF 

(COPY_SYM_ELT_RAF) 

The COPY_SYM_ELT_RAF function copies a symbolic element from a program file into a 

mass storage random-access file. The content of the destination file following this 

function is SDF text. 

This function provides the following options: 

• Either requires the destination file to be empty initially (that is, have no mass storage 

allocated to it) or copies over anything already in the destination file. 

• Copies either the latest symbolic cycle or a specified symbolic cycle of the symbolic 

element being copied. In the latter case, the calling program can specify the cycle 

number as either an absolute number or a number relative to the latest cycle. 


The COPY_SYM_ELT_RAF function packet has the following parameters, each of which 

is described in the following subsections: 




• Work Area 

7–14 7830 9796–013



The structure of the COPY_SYM_ELT_RAF function packet is defined in element 

FP$CPYSYMRAF. See Figure 7–3. 

0 

GENERIC PART 

1 ELT_NAME 

2 

3 

4 ELT_VERSION 

5 

6 ACTION 

7 CYCLE_TYPE CYCLE_NUM 


Figure 7–3. COPY_SYM_ELT_RAF Function Packet Items 


ELT_NAME 

Indicates the name of the element to be copied. A null value is not allowed for this 

item. 


ELT_VERSION 

Indicates the version of the element to be copied. A value of spaces indicates an 

element with no version. A null value is not allowed for this item. 


ACTION 

Indicates what action PCFP takes if the destination file already contains data. 


OVERCOPY = 0 

Indicates that PCFP copies the element text, overwriting the data previously in 

the destination file. 

7830 9796–013 7–15


MUST_BE_EMPTY = 1 

CYCLE_TYPE 

Indicates that PCFP copies the element text only if the destination file is initially 

empty. This value requires the run of the calling program to have read privileges 

for the destination file. 

Indicates if CYCLE_NUM contains an absolute element-cycle value, a relative 

element-cycle value, or no element-cycle value. 



Indicates that PCFP copies the latest symbolic cycle of the symbolic element. 

ABS = 1 

Indicates that PCFP copies only the specific absolute symbolic cycle indicated by 

CYCLE_NUM. 

REL = 2 

CYCLE_NUM 

Indicates that PCFP copies only the specific relative symbolic cycle indicated by 

CYCLE_NUM. 

Indicates which cycle of the symbolic element PCFP copies. If the calling program 

sets CYCLE_TYPE = UNSPECIFIED, it must set CYCLE_NUM to a value of 0. If the 

calling program sets CYCLE_TYPE = ABS, it must set CYCLE_NUM to a value 

between 0 and 62 inclusive. If the calling program sets CYCLE_TYPE = REL, it must 

set CYCLE_NUM to a value between -62 and 0 inclusive. If the symbolic element 

does not contain the cycle specified here, PCFP does not copy the element. 


AMOUNT_COPIED 

Indicates the number of words of text PCFP copied to the destination file. 



The source file identifier parameter names the file from which the element is to be 

copied. The named file must be a program file on sector-addressable mass storage for 

which the calling program has read privileges. See 2.3 for a description of this 

parameter. 

7–16 7830 9796–013



The destination file identifier parameter names the file to which PCFP copies the 

element text. It must be a sector-addressable mass storage file for which the calling 

program has write privileges. See 2.3 for a full description of this parameter. 


This function works with any work area greater than or equal to the minimum size of 

1,000 words. However, the function can work more efficiently with larger work area 

sizes. The actual memory usable by the function varies with the size of the program file 

operated on and the size of the element text copied. This function can make effective 

use of about (200 + 10*N + S) words, where N is the number of elements (deleted and 

undeleted) in the source program file, and S is the word size of the element text copied. 

For most situations, the minimum size work area gives acceptable performance. 

7.3. Copy RAF to Symbolic Element 

(COPY_RAF_SYM_ELT) 

The COPY_RAF_SYM_ELT function creates a symbolic element in a program file from 

the contents of a mass storage random-access file. The content of the source file must 

be SDF text. 

The COPY_RAF_SYM_ELT function provides the following options: 

• Require PCFP to assign the destination file exclusively or not. 

• Initialize an empty destination file as a PF, LPF, standard LEPF, or large LEPF. 

• If a symbolic element with the same name and version already exists in the program 

file, either cause deletion of the original element or do not perform the copy. 

The program calling this function must specify the name, version, and subtype to be 

given to the new element. 


The COPY_RAF_SYM_ELT function has the following parameters, each of which is 





• Work Area 

7830 9796–013 7–17



The structure of the COPY_RAF_SYM_ELT function packet is defined in element 

FP$CPYRAFSYM. See Figure 7–4. 

0 

GENERIC PART 

1 DEST_ELT_NAME 

2 

3 

4 DEST_ELT_VERSION 

5 

6 INIT_DEST_FILE DEST_SYM_SUBTYPE 

7 a ON_CONFLICT 


Figure 7–4. COPY_RAF_SYM_ELT Function Packet Items 


DEST_ELT_NAME 

Indicates the name of the symbolic element PCFP creates. A null value is not 

allowed for this item. 



Indicates the version of the symbolic element PCFP creates. A value of spaces 

indicates an element with no version. A null value is not allowed for this item. 





NONE = 0 



7–18 7830 9796–013

PF = 1 

LPF = 2 









LEPF). 




DEST_SYM_SUBTYPE 

Indicates the subtype of the element to be created. 


SYM = 0 FLT = 16 GSA = 32 

ELT = 1 PNC = 17 MSG = 33 

ASM = 2 TCL = 18 PRT = 34 

COB = 3 MSM = 19 RPG = 35 

FOR = 4 MSD = 20 ADA = 36 

ALG = 5 MAC = 21 PEER = 37 

MAP = 6 APT = 22 C = 38 

DOC = 7 PGA = 23 FHLL = 39 

SEC = 8 QLP = 24 LINK = 40 

SSG = 9 INL = 25 COM = 41 

APL = 10 DCL = 26 PADS = 42 

BAS = 11 SDL = 27 SSDP = 43 

LSP = 12 FDP = 28 FLDP = 44 

PLS = 13 PSP = 29 ASMP = 64 

PL1 = 14 PAS = 30 COBP = 65 

CTS = 15 IPF = 31 FORP = 66 

7830 9796–013 7–19


a = EXCLUSIVE_ASSIGN 



ON_CONFLICT 

Indicates what action PCFP takes if the symbolic element resulting from the copy 

has the same name and version as a symbolic element already in the destination file. 



Indicates that PCFP does create the new element. 


Indicates that PCFP deletes the existing element with same name, version, and 

type, and creates the new element. 

AMOUNT_COPIED 

Indicates the size in words of the symbolic element this function created. 



The source file identifier parameter names the file from which PCFP copies the element 

text. It must be a sector-addressable mass storage file for which the calling program has 

read privileges. The contents of the file must be SDF text. See 2.3 for a full description 

of this parameter. 


The destination file identifier parameter names the file in which PCFP creates the 

symbolic element. Initially, the named file must be either a program file or empty. It 

must reside on sector-addressable mass storage, and the calling program must have 

both read and write privileges for the file. See 2.3 for a description of this parameter. 


The COPY_RAF_SYM_ELT function works with any work area greater than or equal to 

the minimum size of 1,000 words. However, the function works more efficiently with 

larger work area sizes. The actual memory usable by the function varies with the size of 

the program file operated on, and the size of the element text copied. This function can 

make effective use of about (200 + 10*N +S) words, where N is the number of 

elements (deleted and undeleted) in the program file, and S is the word size of the 

7–20 7830 9796–013


element text copied. For most situations, the minimum size work area gives acceptable 

performance. 

7.4. Copy Omnibus Element to RAF 

(COPY_OMN_ELT_RAF) 

The COPY_OMN_ELT_RAF function copies an omnibus element from a program file to a 

mass storage random-access file. It also returns the amount of text copied. 

The COPY_OMN_ELT_RAF function requires the destination file to be empty initially 

(that is, have no mass storage allocated to it), or it copies over anything already in the 



The COPY_OMN_ELT_RAF function has the following parameters, each of which is 





• Work Area 


This structure of the COPY_OMN_ELT_RAF function packet is defined in element 

FP$CPYOMNRAF. See Figure 7–5. 

0 

GENERIC PART 

1 ELT_NAME 

2 

3 

4 ELT_VERSION 

5 

6 b 


Figure 7–5. COPY_OMN_ELT_RAF Function Packet Items 

7830 9796–013 7–21



ELT_NAME 

Indicates the name of the omnibus element PCFP copies. A null value is not allowed 

for this item. 


ELT_VERSION 

Indicates the version of the element PCFP copies. A value of spaces indicates an 

element with no version. A null value is not allowed for this item. 


b = PREVENT_OVERCOPY 





AMOUNT_COPIED 

Indicates the number of words of data PCFP copied to the destination file. 



The source file identifier parameter names the file from which the element is copied. 




The destination file identifier parameter names the file to which the element text is 

copied. It must be a mass storage file (sector-addressable or word-addressable) for 

which the calling program has write privileges. See 2.3 for a full description of this 

parameter. 

7–22 7830 9796–013



The COPY_OMN_ELT_RAF function works with any work area equal to or greater than 



the program file operated on and the size of the element text copied. This function can 

make effective use of about (200 + 10*N + S) words, where N is the number of 



performance. 

7.5. Copy RAF to Omnibus Element 

(COPY_RAF_OMN_ELT) 

The COPY_RAF_OMN_ELT function creates an omnibus element in a program file from 

the contents of a mass storage random-access file. The only restriction on the contents 

of the source file is that it may not contain any holes (unallocated areas). 


• Require PCFP to assign the destination file exclusively, or not. 

• Initialize an empty destination file as a PF, LPF, standard LEPF, or large LEPF. 

• If an omnibus element of the same name and version already exists in the program 

file, either cause deletion of the original element or do not complete the copy. 


The COPY_RAF_OMN_ELT function has the following parameters, each of which is 





• Work Area 

7830 9796–013 7–23



The structure of the COPY_RAF_OMN_ELT function packet is defined in element 

FP$CPYRAFOMN. See Figure 7–6. 

0 

GENERIC PART 

1 DEST_ELT_NAME 

2 

3 

4 DEST_ELT_VERSION 

5 

6 INIT_DEST_FILE DEST_OMN_SUBTYPE 

7 a ON_CONFLICT 


Figure 7–6. COPY_RAF_OMN_ELT Function Packet Items 


DEST_ELT_NAME 

Indicates the name of the omnibus element PCFP creates. A null value is not 

allowed for this item. 



Indicates the version of the omnibus element PCFP creates. A null value is not 

allowed for this item. A value of spaces indicates an element with no version. 





NONE = 0 



7–24 7830 9796–013

PF = 1 

LPF = 2 









LEPF). 




DEST_OMN_SUBTYPE 

Indicates the subtype of the omnibus element PCFP creates. 


SYM = 0 FLT = 16 GSA = 32 

ELT = 1 PNC = 17 MSG = 33 

ASM = 2 TCL = 18 PRT = 34 

COB = 3 MSM = 19 RPG = 35 

FOR = 4 MSD = 20 ADA = 36 

ALG = 5 MAC = 21 PEER = 37 

MAP = 6 APT = 22 C = 38 

DOC = 7 PGA = 23 FHLL = 39 

SEC = 8 QLP = 24 LINK = 40 

SSG = 9 INL = 25 COM = 41 

APL = 10 DCL = 26 PADS = 42 

BAS = 11 SDL = 27 SSDP = 43 

LSP = 12 FDP = 28 FLDP = 44 

PLS = 13 PSP = 29 

PL1 = 14 PAS = 30 

CTS = 15 IPF = 31 

7830 9796–013 7–25





ON_CONFLICT 

Indicates what action PCFP takes if the omnibus element that results from the copy 

has the same name and version as an omnibus element already in the destination 

file. 



Indicates that PCFP does not create the new element. 


Indicates that PCFP deletes the existing element with the same name, version, 

and type, and creates the new element. 

AMOUNT_COPIED 

Indicates the size in words of the element this function created. 



The source file identifier parameter names the file from which PCFP copies the element 

text. It must be a mass storage file (sector-addressable or word-addressable) for which 

the calling program has read privileges. The text of this file must not contain any holes 

(unallocated areas of mass storage). See 2.3 for a full description of this parameter. 


The destination file identifier parameter names the file in which PCFP creates the 

omnibus element. The named file must initially be either a program file or empty. It 

must reside on sector-addressable mass storage, and the calling program must have 

both read and write privileges for the file. See 2.3 for a description of this parameter. 


The COPY_RAF_OMN_ELT function works with any work area equal to or greater than 



the program file operated on, and the size of the element text copied. This function can 

make effective use of about (200 + 10*N + S) words, where N is the number of 


7–26 7830 9796–013



performance. 

7830 9796–013 7–27


7–28 7830 9796–013

Section 8 

Updating Program Files 

This section describes the following functions that update program files. These 

functions are in addition to those in Section 7, which update a program file by copying 

elements. 

• Change Element Attributes (CHG_ELT) 

• Delete Elements (DELETE_ELT) 

• Undelete Elements (UNDELETE_ELT) 

• Pack Program File (PACK_PF) 

• Create Program File Entry Point Table (PREP_PF) 

8.1. Change Element Attributes (CHG_ELT) 

The CHG_ELT function changes the attributes of one or more elements in a program file. 

The elements with attributes that are to be changed can be selected based on their 

name, version, type, subtype, or some combination of these. A partial name and version 

can be specified, as described in 2.6. Only undeleted elements can be selected. 

The following attributes can be changed using this function. The attributes that can be 

changed include all attributes that can be changed with the FURPUR @CHG and 

@CYCLE commands, as they apply to elements. 

• Element name 

• Element version 

The new name and/or version specified by the calling program may include wild-card 

characters, indicating that the corresponding characters from the original name or 

version are to be retained. See 2.6 for details on this. 

• Element subtype (applies to symbolic and omnibus elements only) 

• Maximum number of symbolic cycles retained 

If this change causes the maximum to become smaller than the number of cycles 

currently retained, PCFP recopies the text of the element so that only images within 

the new cycle limit are retained. 

• Date and time the element was created 

7830 9796–013 8–1


The CHG_ELT function has the following options: 

• If CHG_ELT would cause a duplicate element (same name, version, and type) to be 

created, PCFP takes one of the following two actions: 

− Marks the existing element as deleted and proceeds with the change 

− Leaves the element unchanged 

• Requires PCFP to assign the program file exclusively 

• Returns name, version, type, subtype, and result indicator for 

− Each element that was selected and successfully changed 

− Each element that was selected but could not be changed 

− Each element that was selected, whether it was changed or not 


The result indicator returned for each element indicates whether or not the change 

could be completed for that element, and any error or warning associated with 

changing the attributes of that element. 

In all cases, this function returns the number of elements it selected for change, the 

number it successfully changed, and the number that it could not change. 

When this function causes one or more relocatable elements to be deleted from the 

program file (due to name-version-type conflict with a renamed element), it removes any 

relocatable entry point table that previously existed in the program file. However, when 

this function causes similar deletion of an object module, it does not remove the object 

module entry point table. 

When this function causes one or more procedure symbolic elements to be deleted from 

the program file, it also deletes any procedure entries associated with those elements. 


The CHG_ELT function has the following parameters, each of which is described in the 





• Work Area 

8–2 7830 9796–013


0 

1 

2 

3 

4 

5 

10 

11 

12 

13 

14 

15 

6 a b c d 


The structure of the CHG_ELT function packet is defined in element FP$CHGELT. See 

Figure 8–1. 

GENERIC PART 


ELT_NAME 

ELT_VERSION 



9 f f f f f f f f f f f f f f f f f f 

NEW_ELT_NAME 

NEW_ELT_VERSION 

16 g h i j NEW_OMN_SYM_SUBTYPE 

17 NEW_CYCLE_LIMIT 




21 NUM_FAILED 


ELT_NAME 

Figure 8–1. CHG_ELT Function Packet Items 

7830 9796–013 8–3


Indicates the name or pattern of the name of the elements that PCFP changes. The 


and the asterisk ( * ) wild-card characters as described in 2.6. A null value indicates 

that the elements are selected for change without regard to their names. 


ELT_VERSION 

Indicates the version or pattern of the version of the elements that PCFP changes. 

The value that the calling program supplies for this item may contain the question 

mark ( ? ) and the asterisk ( * ) wild-card characters as described in 2.6. A null value 

indicates that the elements are selected for change without regard to their versions. 


a = ABS_TYPE 

Indicates whether PCFP changes absolute elements. 


b = OMN_TYPE 

Indicates whether PCFP changes omnibus elements. 


c = REL_TYPE 

Indicates whether PCFP changes relocatable elements. 


d = SYM_TYPE 

Indicates whether PCFP changes symbolic elements. 


8–4 7830 9796–013


If the calling program sets items ABS_TYPE, OMN_TYPE, REL_TYPE, and SYM_TYPE to 

all FALSE or all TRUE, PCFP selects elements to be changed regardless of their types. 


Indicates which subtypes of omnibus and symbolic elements PCFP changes. Each 

item in this array occupies a single bit. If the calling program sets any entries in this 

array to TRUE (1), only omnibus and symbolic elements that have a numeric subtype 

corresponding to a TRUE entry are changed. If the calling program sets no item in 

the array to TRUE, omnibus and symbolic elements are changed regardless of 

subtype. This item applies only to symbolic and omnibus elements; it does not 

affect the selection of elements of other types. 



Indicates which subtypes of absolute elements PCFP changes. Each item in this 

array occupies a single bit. If the calling program sets any entries in this array to 


TRUE entry are changed. If the calling program sets no item in the array to TRUE, 

absolute elements are changed regardless of subtype. This item applies only to 

absolute elements; it does not affect the selection of elements of other types. 


NEW_ELT_NAME 

Indicates the new name for the element. The value the calling program supplies for 

this item may contain the question mark ( ? ) wild-card character. PCFP replaces 

each question mark with the corresponding character in the original element name. 

If this value is null, PCFP does not change the names of the elements selected. 


NEW_ELT_VERSION 

Indicates the new version for the element. The value the calling program supplies 

for this item may contain the question mark ( ? ) wild-card character. PCFP replaces 

each question mark with the corresponding character in the original element version. 

If the value PCFP supplies for this item is all spaces, the new version name is made 

all spaces. If this value is null, PCFP does not change the versions of the elements 

selected. 


7830 9796–013 8–5


g = CHG_OMN_SYM_SUBTYPE 

Indicates whether PCFP changes the subtype of the omnibus and symbolic 

elements it selects. When the calling program sets this item to TRUE, it must also 

set the new subtype in NEW_OMN_SYM_SUBTYPE. 


h = CHG_DATE_TIME 

Indicates whether PCFP changes the dates and times of the elements it selects. 

Setting CHANGE_DATE_TIME = FALSE indicates they are not changed. Setting 

CHANGE_DATE_TIME = TRUE indicates they are changed to the date and time 

when PCFP performs the operation. 


i = EXCLUSIVE_ASSIGN 

Indicates whether or not PCFP must assign the program file exclusively prior to 

performing the operation. 


j = PROCEED_ON_CONFLICT 

Indicates the action PCFP takes if an element is being given a new name and version 

that would cause it to have the same name, version, and type as an existing 

element. FALSE indicates that PCFP does not perform the change for that element, 

and TRUE indicates that PCFP performs the change for that element after deleting 

the existing element with the same name, version, and type. 


8–6 7830 9796–013

NEW_OMN_SYM_SUBTYPE 


Indicates the new subtype PCFP gives to the symbolic and omnibus elements it 

selects. The calling program can set this item to a nonzero value only if it also sets 

CHANGE_OMN_SYM_SUBTYPE = TRUE. 


SYM = 0 FLT = 16 GSA = 32 

ELT = 1 PNC = 17 MSG = 33 

ASM = 2 TCL = 18 PRT = 34 

COB = 3 MSM = 19 RPG = 35 

FOR = 4 MSD = 20 ADA = 36 

ALG = 5 MAC = 21 PEER = 37 

MAP = 6 APT = 22 C = 38 

DOC = 7 PGA = 23 FHLL = 39 

SEC = 8 QLP = 24 LINK = 40 

SSG = 9 INL = 25 COM = 41 

APL = 10 DCL = 26 PADS = 42 

BAS = 11 SDL = 27 SSDP = 43 

LSP = 12 FDP = 28 FLDP = 44 

PLS = 13 PSP = 29 ASMP = 64 

PL1 = 14 PAS = 30 COBP = 65 

CTS =15 IPF = 31 FORP = 66 

The values ASMP, COBP, and FORP are not valid for omnibus elements. If the 

calling program attempts to give an omnibus element one of these subtypes, PCFP 

does not change that element. 

NEW_CYCLE_LIMIT 

Indicates the new symbolic cycle limit that PCFP gives to the symbolic elements that 

it selects. For any element selected where this value is less than the number of 

cycles currently retained, PCFP recopies the element text so that the number of 

cycles actually retained is reduced to satisfy the new maximum. When the calling 

program sets this item to zero, PCFP does not change the cycle limit for any 

element. 


7830 9796–013 8–7



Indicates which of the elements PCFP selected have individual information returned 

to the calling program. 


NONE = 0 

Indicates that PCFP returns individual information for no elements. 


Indicates that PCFP returns individual information only for each element that it 

selected but was not able to change. 


Indicates that PCFP returns individual information only for each element that it 

selected and actually changed. 

ALL_INFO = 3 

INFO_DETAIL 

Indicates that PCFP returns individual information for each element it selected, 

whether or not the element was successfully changed. 

For each individual element for which information is returned, indicates what parts of 

the element information PCFP returns. This item is ignored if the calling program set 

INFO_TO_RETURN = NONE. 


SHORT = 0 

Indicates that for each element that has return information, PCFP returns only 

the following items: RESULT_INDICATOR, ELT_NAME, ELT_VERSION, 

ELT_TYPE, ELT_SUBTYPE, SEQ_NUM. 

LONG = 1 

Indicates that PCFP returns all of the element information described in 6.2.4 for 

each element. 

NUM_SELECTED 

Indicates how many elements PCFP selected, whether they were changed 

successfully or not. 


8–8 7830 9796–013



Indicates how many of the elements PCFP selected were actually changed. 


NUM_FAILED 

Indicates how many of the elements PCFP selected were not changed. The reason 

for each failure is indicated by RESULT_INDICATOR in the return entry, if the calling 

program requested this information to be returned. In all cases, NUM_SELECTED = 

NUM_SUCCESSFUL + NUM_FAILED. 



The file identifier parameter names the file in which elements are to be changed. The 


calling program has both read and write privileges. See 2.3 for a full description of this 

parameter. 


PCFP returns one entry for each element it selected, subject to the constraints indicated 

by INFO_TO_RETURN in the function packet. See 6.2.4 for a description of these 

entries. 

For those elements that PCFP selected but was not able to change, PCFP sets the item 

RESULT_INDICATOR in the return entry to a value other than FP_ERR_NONE (0) to 

indicate the error and its cause. For the CHG_ELT function, RESULT_INDICATOR can 

have the following values for elements that PCFP was not able to change: 

FP_WARN_ELT_CONFLICT 

Indicates that PCFP was not able to change the element because the program file 

already contains an element with the same type that has a name and version 

matching the new name and version given to this element. This value can be 

returned only if the calling program set PROCEED_ON_CONFLICT = FALSE in the 

function packet. 

FP_WARN_BAD_ELT_NAME 

Indicates that PCFP was unable to change the element because the new name 

generated for the element contains an embedded space. 

FP_WARN_BAD_ELT_VERSION 

Indicates that PCFP was unable to change the element because the new version 

generated for the elements contain an embedded space. 

7830 9796–013 8–9


FP_WARN_BAD_SUBTYPE 


Indicates that PCFP was unable to change the element because the new subtype 

specified is not legal for an omnibus element. 

The CHG_ELT function can always operate with any work area equal to or greater than 

the minimum size of 1,000 words. However, this function can work more efficiently 

with a larger work area. The actual memory usable by this function varies with the size 

of the program file on which it operates. This function can make effective use of about 

(350 + 10*N) words, where N is the number of elements (deleted and undeleted) in the 

program file. Thus, a work area size larger than the minimum can be useful with a 

program file with more than 65 elements. The maximum size work area of 20,000 

words is useful for program files containing 2,000 elements or more. 

8.2. Delete Elements (DELETE_ELT) 

The DELETE_ELT function deletes one or more elements from a program file. It 

provides the capability of the FURPUR @DELETE command as it applies to elements. It 

also provides some of the capabilities provided by the FURPUR @PACK command. 

The elements to be deleted can be selected based upon name, version, type, subtype, 

or some combination of these. A partial name and version can be specified, as 

described in 2.6. Only undeleted elements can be selected. 

The DELETE_ELT function provides the following options: 

• Returns name, version, type, and subtype of each element that is deleted 

• Requires PCFP to assign the program file exclusively 

In all cases, this function returns the number of elements successfully deleted. 

When this function deletes one or more relocatable elements from the program file, it 

removes any relocatable entry point table that previously existed in the program file. 

However, when this function deletes an object module absolute element from the 

program file, it does not remove any existing object module entry point table. 

When this function deletes one or more procedure symbolic elements from the program 

file, it also deletes any procedure entries associated with those elements. 

8–10 7830 9796–013



The DELETE_ELT function has the following parameters, each of which is described in 





• Work Area 


0 

1 

2 

3 

4 

5 

6 a b c d 

This structure of the DELETE_ELT function packet is defined in element FP$DELELT. 


GENERIC PART 


ELT_NAME 

ELT_VERSION 



9 f f f f f f f f f f f f f f f f f f INFO_TO_RETURN 

10 g INFO_DETAIL 


Figure 8–2. DELETE_ELT Function Packet Items 

7830 9796–013 8–11



ELT_NAME 

Indicates the name or pattern of the name of the elements that PCFP deletes. The 



that the elements are deleted without regard to element name. 


ELT_VERSION 

Indicates the version or pattern of the version of the elements PCFP deletes. The 



that the elements are deleted without regard to version. 


a = ABS_TYPE 

Indicates whether PCFP deletes absolute elements. 


b = OMN_TYPE 

Indicates whether PCFP deletes omnibus elements. 


c = REL_TYPE 

Indicates whether PCFP deletes relocatable elements. 


d = SYM_TYPE 

Indicates whether PCFP deletes symbolic elements. 


8–12 7830 9796–013


If the calling program sets items ABS_TYPE, OMN_TYPE, REL_TYPE, and SYM_TYPE all 

to FALSE or all to TRUE, PCFP deletes elements regardless of their types. 


Indicates which subtypes of omnibus and symbolic elements PCFP deletes. Each 



corresponding to a TRUE entry are deleted. If the calling program sets no item in the 

array to TRUE, omnibus and symbolic elements are selected regardless of subtype. 

This item applies only to symbolic and omnibus elements; it does not affect the 

selection of elements of other types. 



Indicates which subtypes of absolute elements PCFP deletes. Each item in this 



TRUE entry are deleted. If the calling program sets no item in the array to TRUE, 

absolute elements are deleted regardless of subtype. This item applies only to 

absolute elements; it does not affect the selection of elements of other types. 



Indicates whether PCFP returns information about the individual elements it deleted 

to the calling program. 


NONE = 0 

Indicates that PCFP does not return individual information about each element 

deleted. 

ALL_INFO = 3 

Indicates that PCFP returns individual information about each element deleted. 


Indicates whether or not PCFP must assign the program file exclusively prior to 

performing the operation. 


7830 9796–013 8–13


INFO_DETAIL 

For each individual element for which information is returned, indicates what parts of 

the element information PCFP returns. This item is ignored if the calling program set 



SHORT = 0 

Indicates that only the following items will be returned: RESULT_INDICATOR, 

ELT_NAME, ELT_VERSION, ELT_TYPE, ELT_SUBTYPE, and ELT_SEQ_NUM. 

LONG = 1 

Indicates that all of the element information described in 6.2.4 is returned. 

NUM_SELECTED 

Indicates how many elements PCFP deleted. 



The file identifier parameter names the file in which elements are to be deleted. The 



parameter. 


PCFP returns an entry for each element it deleted, subject to the constraints indicated by 

INFO_TO_RETURN in the function packet. See 6.2.4 for a description of these entries. 

For the DELETE_ELT function, items that PCFP selects for deletion can always be 

deleted successfully. Therefore, the item RESULT_INDICATOR in the return entry 

always has the value FP_ERR_NONE(0). 


The DELETE_ELT function can always operate with any work area that is equal to or 

greater than the minimum size of 1,000 words. However, this function can work more 

efficiently with a larger work area. The actual memory usable by this function varies with 

the size of the program file on which it operates. This function can make effective use 

of about (350 + 10*N) words, where N is the number of elements (deleted and 

undeleted) in the program file. Thus, a work area size larger than the minimum is useful 

with a program file with more than 65 elements. The maximum size work area of 

20,000 words is useful for program files containing 2,000 elements or more. 

8–14 7830 9796–013

8.3. Undelete Elements (UNDELETE_ELT) 


The UNDELETE_ELT function undeletes one or more elements from a program file. 

All elements with the same element name, version name, and type make up an 

element/version/type set. At most, one of the elements in the set may be undeleted. 

The rest of the elements in the set are deleted. The UNDELETE_ELT function allows 

selection and undeletion of any deleted member of the element/version/type set. If the 

set contains an undeleted element before the function is called, that element is changed 

to deleted. 

Note that once the PACK_PF function is called (see 8.4), all deleted members of all 

element/version/type sets are permanently removed and are no longer available to be 

undeleted. 

The elements to be undeleted can be selected based on name, version, type, subtype, 

sequence number, or some combination of these. A partial name and version can be 

specified, as described in 2.6. Only deleted elements can be selected. 

Table 8–1 illustrates the concept of absolute and relative element sequence numbers 

that is unique to the UNDELETE_ELT function. The columns represent a set of five 

elements that have the same element name, version name, and type. In this example, 

the element with the highest sequence number is undeleted and the other four 

elements are deleted. This is the normal case for program files. The rows identify how 

the individual members of the set are identified by absolute sequence number and by 

relative sequence number. The element with the highest absolute sequence number in 

the element/version/type set always has relative sequence number 0. The 

UNDELETE_ELT function can be used to change which member of the 

element/version/type set is undeleted (No in the Deleted row), but the relative sequence 

numbers of the set remain unchanged. Using Table 8–1 as an example, if 

UNDELETE_ELT changes absolute sequence number 62 to undeleted and absolute 

sequence number 112 to deleted, these two elements are still identified as relative 

sequence numbers -2 and 0, respectively. 

Table 8–1. Absolute and Relative Sequence Numbers 

(sample) 

Attributes Element/Version/Type Set Members 

Deleted Yes Yes Yes Yes No 

Absolute 

Sequence 

Number 

Relative 

Sequence 

Number 

13 

-4 

48 

-3 

7830 9796–013 8–15 

62 

-2 

78 

-1 

112 

0


The UNDELETE_ELT function provides the following options: 

• Requires PCFP to assign the file exclusively or not. 

• If UNDELETE_ELT would cause an undeleted element with the same name, version, 

and type to be deleted, do one of the following: 

− Delete the element and proceed with the undelete 

− Do not delete the element and do not proceed with the undelete 

• Sequence number is used to select elements to be undeleted by one of the 

following methods (as illustrated in Table 8–1): 

− A relative sequence number identifies a member of each element/version/type 

set to be undeleted. 

− An absolute sequence number identifies one program file element to be 

undeleted. 

• Returns name, version, type, subtype, and result indicator for 

− Each element that was selected and successfully undeleted 

− Each element that was selected, but not undeleted 

− Each element that was selected, whether it was undeleted or not 


In all cases, the UNDELETE_ELT function returns the number of elements it selected, 

the number it successfully undeleted, and the number it did not undelete. 

When this function undeletes one or more relocatable elements, it removes any 

relocatable entry point table that previously existed in the program file. However, when 

this function undeletes one or more object module absolute elements in the program 

file, it does not remove any existing object module entry point tables. 

When the function undeletes one or more procedure symbolic elements, it also 

undeletes all procedure table entries associated with those elements. When the 

function deletes one or more procedure symbolic elements, it also deletes all procedure 

table entries associated with those elements. 


The UNDELETE_ELT function has the following parameters, each of which is described 





• Work Area 

8–16 7830 9796–013


0 

1 

2 

3 

4 

5 

6 a b c d 

The structure of the UNDELETE_ELT function packet is defined in element 

FP$UNDELELT. See Figure 8–3. 

GENERIC PART 


ELT_NAME 

ELT_VERSION 




9 f f f f f f f f f f f f f f f f f f SEQ_NUM_TYPE 

10 g h SEQ_NUM 




14 NUM_FAILED 

Figure 8–3. UNDELETE_ELT Function Packet Items 


ELT_NAME 

Indicates the name or pattern of the name of the elements that this function 

undeletes. The value the calling program supplies for this item may contain the 


null value indicates the elements are undeleted without regard to element name. 


7830 9796–013 8–17


ELT_VERSION 

Indicates the version or pattern of the version of the elements that this function 

undeletes. The value the calling program supplies for this item may contain the 


null value indicates the elements are undeleted without regard to version. 


a = ABS_TYPE 

Indicates whether absolute elements are undeleted. 


b = OMN_TYPE 

Indicates whether omnibus elements are undeleted. 


c = REL_TYPE 

Indicates whether relocatable elements are undeleted. 


d = SYM_TYPE 

Indicates whether symbolic elements are undeleted. 


If the calling program sets items ABS_TYPE, OMN_TYPE, REL_TYPE and SYM_TYPE all 

to FALSE or all to TRUE, elements are undeleted without regard to their type. 


Indicates which subtypes of omnibus and symbolic elements are undeleted. Each 



corresponding to the TRUE entry are undeleted. If the calling program sets no item 

in the array to TRUE, omnibus and symbolic elements are undeleted without regard 

to their subtype. This item applies only to omnibus and symbolic elements and does 

not affect the selection of elements of other types. 

Note that the CHG_ELT, COPY_ELT, COPY_RAF_OMN_ELT and 

COPY_RAF_SYM_ELT functions can be used to create element/version/type sets 

where the set members have different subtypes. An element/version/type set will 

not be selected for undeletion unless all of its members match subtype 

specifications. 

8–18 7830 9796–013




Indicates which subtypes of absolute elements are undeleted. Each item in this 


TRUE (1), only absolute elements that have a numeric subtype corresponding to the 

TRUE entry are undeleted. If the calling program sets no item in the array to TRUE, 

absolute elements are undeleted without regard to their subtype. This item applies 

only to absolute elements and does not affect the selection of elements of other 

types. 

Note that the COPY_ELT function can be used to create element/version/type sets 

where the set members have different subtypes. An element/version/type set will 

not be selected for undeletion unless all of its members match subtype 

specifications. 


SEQ_NUM_TYPE 

Indicates if SEQ_NUM contains a relative sequence number, identifying a member of 

each element/version/type set, or an absolute sequence number, identifying a single 

element in the program file. 


REL = 0 

Indicates that SEQ_NUM contains a relative sequence number that identifies a 

member of each element/version/type set to undelete. 

ABS = 1 

Indicates that SEQ_NUM contains an absolute sequence number that identifies 

a single element in the program file. 


Indicates whether or not the program file must be assigned exclusively. 


h = ALLOW_DELETION 

Indicates what action to take if undeletion of an element would cause the deletion of 

another member of the element/version/type set. FALSE indicates that the 

undeleted element is not to be deleted, so the selected element is not undeleted. 

TRUE indicates that deletion is allowed. The undeleted element is deleted before 

the selected element is undeleted. 


7830 9796–013 8–19


SEQ_NUM 

Indicates the specific sequence number to undelete. No undeletion occurs if the 

indicated sequence number does not exist, if it is already undeleted, or if there is 

already an undeleted member of the element/version/type set and the 

ALLOW_DELETION item does not allow its deletion. 

If the calling program sets SEQ_NUM_TYPE = REL, it must set this item to a value 

between -26,145 and 0 inclusive. 

If the calling program sets SEQ_NUM_TYPE = ABS, it must set this item to a value 

between 1 and 26,146 inclusive. It must also set the ELT_NAME and ELT_VERSION 

items to null values and it must set the ABS_TYPE, OMN_TYPE, REL_TYP and 

SYM_TYPE items, the OMN_SYM_SUBTYPE condition array and the ABS_SUBTYPE 

condition array to FALSE. 

Data Type: signed integer range (-26,145 through 26,146) 


Indicates which of the selected elements have individual information returned to the 



NONE = 0 

Indicates that individual information is returned for no elements. 


Indicates that individual information is returned only for elements that are 

selected but not undeleted. 


Indicates that individual information is returned only for elements that are 

selected and successfully undeleted. 

ALL_INFO = 3 

INFO_DETAIL 

Indicates that individual information is returned for all elements that are selected, 

without regard to whether or not they are successfully undeleted. 

For each element for which information is returned, indicates what parts of the 

element information is returned. This item is ignored if the calling program sets 



8–20 7830 9796–013

SHORT = 0 


Indicates that for each element for which information is returned, the element 

items RESULT_INDICATOR, ELT_NAME, ELT_VERSION, ELT_TYPE, 

ELT_SUBTYPE, and ELT_SEQ_NUM are returned. 

LONG = 1 

Indicates that for each element for which information is returned, all information 

described in 6.2.4 is returned. 

SUMMARY = 3 

Indicates that instead of returning individual information for each element, PCFP 

summarizes the information and returns it in a single summary entry, as 


NUM_SELECTED 

Indicates the number of element/version/type sets that matched function packet 

specifications for element name, version, type and subtype. 



Indicates the number of elements actually undeleted. 


NUM_FAILED 

Indicates the number of element/version/type sets selected for which no element 

was undeleted. No element was undeleted because the relative sequence number 

(SEQ_NUM) does not exist in the element/version/type set, because the relative 

sequence number is already undeleted or because a member of the 

element/version/type set is undeleted and the ALLOW_DELETION specification 

does not allow its deletion. If the calling program requested return of error 

information, the reason that the element was not undeleted is returned in the 

RESULT_INDICATOR return entry item. 

Serious errors that cause termination of the UNDELETE_ELT function are not 

counted in this item. These errors are reported in the generic part of the function 

packet, as described in 2.4.1. 

When the function completes, NUM_SELECTED is equal to the sum of 

NUM_SUCCESSFUL and NUM_FAILED. When the function terminates because of 

an error, NUM_SELECTED can be one greater than the sum of NUM_SUCCESSFUL 

and NUM_FAILED. 


7830 9796–013 8–21



The file identifier parameter names the file in which elements are to be undeleted. The 



parameter. 


When the function packet item INFO_DETAIL is set to SHORT or LONG, one entry is 

returned for each element indicated by the function packet item INFO_TO_RETURN. 

See 6.2.4 for a description of these entries. 

For elements that were successfully undeleted, the RESULT_INDICATOR item in the 

return entry is set to one of the following values: 

FP_ERR_NONE 

Indicates that the element was successfully undeleted. 

FP_INFO_PROC_TBL_ERR 

Indicates that the element was successfully undeleted, but that some or all of the 

procedure table entries associated with the element could not be processed. When 

this error is detected, the function is terminated. 

For elements that were selected but were not undeleted, the RESULT_INDICATOR item 

in the return entry is set to one of the following values: 

FP_WARN_ELT_REL_SEQ_NUM_ERR 

Indicates that for this element/version/type set the relative sequence number 

specified in the SEQ_NUM item does not exist. The return entry is the member of 

the element/version/types set with the lowest sequence number. 

FP_WARN_ELT_UNDELETED 

Indicates that the selected element was already undeleted. 

FP_WARN_ELT_DELETE_NOT_ALLOWED 

indicates that the selected element was not undeleted because another member of 

the element/version/type set was undeleted and the ALLOW_DELETION 

specification did not allow its deletion. 

When the function packet item INFO_DETAIL is set to SUMMARY, a single entry is 

returned summarizing the undelete function for elements indicated by the function 

packet item INFO_TO_RETURN. The item NUM_RTN_ENTRIES in the Return 

Information part of the function packet is set to 1. See 7.1.5 for a description of return 

entry. 

8–22 7830 9796–013



The UNDELETE_ELT function can always operate with any work area greater than or 

equal to the minimum size of 2,000 words. In many situations this function works more 

efficiently with a larger work area size. The actual work area usable by this function 

varies with the size of the program file it operates on, the number of elements it 

undeletes, and options specified in the function packet. 

The formula below can be used to calculate the size of the work area usable by the 

function. All of the information needed in this calculation can be obtained using the 

ACQ_BASIC_PF_INFO function, described in 6.1. 

The usable size of the work area can be calculated by the formula (350 + 10*T + U + V + 

W), where: 

350 The fixed function requirement. 

T The number of elements in the file. This corresponds to the 

ACQ_BASIC_PF_INFO return value ELT_NUM_ENTRIES. 

U The size of a condition array that is required when either ELT_NAME or 

ELT_VERSION contain wild-card characters or null values. The size of the 

condition array is (T / 36). 

V The size of a condition array that is required when SEQ_NUM_TYPE has a value 

of REL (0). The size of the condition array is (T / 36). 

W The number of procedure elements to undelete or delete with the function, 

when either ELT_NAME or ELT_VERSION contain wild-card characters or null 

values. The total number of procedure elements and the number of undeleted 

procedure elements are contained in the ACQ_BASIC_PF_INFO return values 

NUM_PROC_ELTS and NUM_UNDELETED_PROC_ELTS, respectively. 

As described in 2.4.1, the total work area size plus the return area size cannot exceed 

approximately 238,000 words. 

The maximum defined work area size of 52,000 words allows UNDELETE_ELT to 

efficiently process a standard program file with the maximum of 5,000 elements and any 

combination of function packet options. 

When the maximum possible work area size (about 238,000 words) is specified and 

return area size is specified as zero, there is sufficient work area to efficiently process a 

large program file with approximately 23,500 elements and any combination of function 

packet options. 

7830 9796–013 8–23


8.4. Pack Program File (PACK_PF) 

The PACK_PF function removes from a program file deleted elements, their associated 

procedure table entries, if any, and their associated element text. The element text 

associated with deleted elements and the space occupied by Object Module Entry Point 

Tables are removed by PACK_PF and are sometimes referred to as dead space. 

The PACK_PF function exclusively assigns the file on which it operates. Before 

modifying the file in any way, the structure of the file is checked for validity. The 

function proceeds only if the file passes all validity checks. If the file contains a 

Relocatable Entry Point Table, it is removed. If the file contains Object Module Entry 

Point Tables, they are removed. If no elements remain after removing deleted elements 

from the file and if the file is a standard program file (PF), the function erases the file. If 

elements do remain or if the file is a large program file (LPF) or a large element program 

file (LEPF), the file retains its structure. After completion, the function returns the 

following information: 

• Number of elements and amount of mass storage released from the file 

• Number and type of elements and procedure table entries remaining in the file 

• Number of elements and procedure table entries that can be added to the file 

The PACK_PF function can use either the standard method or the copy method to pack 

files. An option enables selection of the desired method. Both standard program files 

and large program files can be packed using either pack method. 

The standard method packs the file in place and is performed in two main steps. 

• In the first step, all deleted element table entries and all associated procedure table 

entries are removed and the tables are rebuilt and rewritten to mass storage. No 

deleted element text is removed during this step. 

• In the second step, the text of remaining undeleted elements is copied, if necessary, 

so that the text of each element immediately follows the text of the previous 

element. This closes up the element text for the file and removes the dead space 

previously occupied by deleted element text. After the element text is copied for 

each element, the element table entry is updated and is normally written to mass 

storage immediately. If the element has associated procedure table entries, they are 

updated and are normally written to mass storage immediately. An option is 

available to delay the writing of updated element table and procedure table entries to 

improve performance. 

The copy method packs the file externally using a dynamically assigned temporary file 

and is performed in two main steps. 

• In the first step, all undeleted element table entries, there associated procedure 

table entries, if any, and there associated element text are copied to the temporary 

file using the COPY_ELT function. 

• In the second step, the entire temporary file is copied back to the original program 

file using the COPY_RAF_RAF function. Unique error codes associated with the 

copy method are described in A.2.8. 

8–24 7830 9796–013


If neither the standard method nor the copy method is selected, the PACK_PF function 

determines the method to use to pack a file. If there is sufficient work area and if the 

program file element table and all procedure tables are less than or equal to 65,436 

words in length (6,529 elements, 16,324 procedures, or 8,162 eight-word COBOL 

procedures), the standard method is used to pack the file. Otherwise, the copy method 

is used. 

Each pack method has its own work area requirements, described in 8.5.4. Appendix C 

contains additional technical information on the operation of the two pack methods. It 

includes a detailed function performance discussion and comparison (C.1, C.2, and C.3) 

and a discussion of the contents of the file in case of system failure or function failure 

(C.4). 

The PACK_PF function provides the following options: 

• Do not release mass storage, release unused mass storage back to the initial reserve 

of the file, or release all unused mass storage. 

• Zero-fill all mass storage before it is released. 

• Select the standard method, the copy method, the copy method only if there is 

insufficient work area for the standard method, or let the PACK_PF function select 

the pack method. 

• When the standard method is used, delay writing the updated element table and 

procedure table entries to reduce the amount of I/O and improve performance. 

The PACK_PF function does not provide the following capabilities of the FURPUR 

@PACK command: 

• Remove all elements except undeleted elements of a specific type from a program 

file. A combination of the A, O, R, or S options on the @PACK command provides 

this capability in FURPUR. The same result can be achieved using PCFP by 

performing a DELETE_ELT function followed by a PACK_PF function. 

• Create a new Relocatable Entry Point Table and a new Object Module Entry Point 

Table. The @PACK,P command provides this capability in FURPUR. The same result 

can be achieved using PCFP by performing a PACK_PF function followed by a 

PREP_PF function. 

• Reduce the program file tables to their minimum sizes. The @PACK,M command 

provides this capability in FURPUR. This capability is not available in PCFP. 


The PACK_PF function has the following parameters, each of which is described in the 

following subsection: 



• Work Area 

7830 9796–013 8–25



The structure of the PACK_PF function is defined in element FP$PACKPF. 


GENERIC PART 

0 a b aa bb STORARE_TO_RELEASE 

1 NEXT_TEXT_LOCATION 

2 TOC_SIZE 

3 TEXT_SIZE 

4 LATEST_ABS_SEQ_NUM 

5 ELT_NUM_ENTRIES ELT_OPEN_ENTRIES 

6 MASM_PROC_NUM_ENTRIES MASM_PROC_OPEN_ENTRIES 

7 COBOL_PROC_NUM_ENTRIES COBOL_PROC_OPEN_ENTRIES 

8 FTN_PLUS_PROC_NUM_ENTRIES FTN_PLUS_PROC_OPEN_ENTRIES 

9 REL_EP_NUM_ENTRIES REL_EP_OPEN_ENTRIES 



12 NUM_DELETED_ELTS 

13 DEAD_SPACE 


Figure 8–4. PACK_PF Function Packet Items 

a = ZERO_RELEASED_STORAGE 

Indicates whether PCFP zero-fills all mass storage that it releases. 


b = REDUCE_IO 

Indicates whether the standard method writes individual element table entries and 

procedure table entries as they are updated (FALSE) or whether writes are delayed 

until all program file table updates are complete (TRUE). The effect of this item on 

function performance and on the contents of the file in case of system failure or 

function failure, is discussed in Appendix C. 


8–26 7830 9796–013

aa = PACK_METHOD 

Indicates the method to be used to pack the file. 


DEFAULT = 0 


The PACK_PF function selects the method to be used, based on the supplied 

work area size and the size of the program file tables. 

STANDARD = 1 

Use the standard method to pack the file. 

COPY = 2 

Use the copy method to pack the file. 

COPY_IF_NECESSARY = 3 

Use the standard method to pack the file, unless the supplied work area size is 

not sufficient. In this case, use the copy method to pack the file. 

bb = METHOD_USED 

Indicates the method actually used by the PACK_PF function to pack the file 


STANDARD = 1 

The standard method was used. 

COPY = 2 

The copy method was used. 


Indicates to what extent PCFP releases unused mass storage from the program file 

after the file is packed. 


NONE = 0 

Does not release any unused mass storage. 


Releases any unused mass storage above the initial reserve of the file. 

7830 9796–013 8–27



Releases all unused mass storage from the file, including any within the initial 

reserve. 

Note: All remaining items in this function packet contain return values. These items 

are the same as those returned by ACQ_BASIC_PF_INFO. Except as indicated, these 

items apply to the file after it is packed. 

NEXT_TEXT_LOCATION 

Indicates the location (in words) where the text of the next element added to the 

program file would be written. 


TOC_SIZE 

Indicates the amount of mass storage (in words) still occupied by the program-file 

tables of contents in the program file. 


TEXT_SIZE 

Indicates the amount of mass storage (in words) occupied by the text of all elements 

remaining in the program file. 


LATEST_ABS_SEQ_NUM 

Indicates the sequence number of the latest absolute element in the program file. A 

value of zero implies that the file contains no absolute elements. 


ELT_NUM_ENTRIES 

Indicates the number of entries remaining in the element table of contents. 


ELT_OPEN_ENTRIES 

Indicates the number of additional entries the element table of contents could 

contain at its currently allocated size. (See notes following item descriptions.) 


8–28 7830 9796–013

MASM_PROC_NUM_ENTRIES 


Indicates the number of entries remaining in the MASM procedure table of contents. 


MASM_PROC_OPEN_ENTRIES 

Indicates the number of additional entries the MASM procedure table of contents 

could contain at its currently allocated size. (See notes following item descriptions.) 


COBOL_PROC_NUM_ENTRIES 

Indicates the number of entries remaining in the COBOL procedure table of 

contents. 


COBOL_PROC_OPEN_ENTRIES 

Indicates the number of additional entries the COBOL procedure table of contents 

could contain at its currently allocated size. (See notes following item descriptions.) 


FTN_PLS_PROC_NUM_ENTRIES 

Indicates the number of entries remaining in the FORTRAN-PLUS procedure table of 

contents. 


FTN_PLS_PROC_OPEN_ENTRIES 

Indicates the number of additional entries the FORTRAN-PLUS procedure table of 

contents could contain at its currently allocated size. (See notes following item 



REL_EP_NUM_ENTRIES 

Indicates the number of entries remaining in the relocatable entry point table of 

contents. Since PACK_PF removes the entry point tables, this item always has value 

0, and is included only to maintain correspondence between this function and 

ACQ_BASIC_PF_INFO. 


7830 9796–013 8–29


REL_EP_OPEN_ENTRIES 

Indicates the number of additional entries the relocatable entry point table of 

contents could contain at its currently allocated size. Since PACK_PF removes the 

entry point tables, this item always has value 0, and is included only to maintain 

correspondence between this function and ACQ_BASIC_PF_INFO. 


NUM_ABS_ELTS 

Indicates the number of absolute elements remaining in the program file. 


NUM_OMN_ELTS 

Indicates the number of omnibus elements remaining in the program file. 


NUM_REL_ELTS 

Indicates the number of relocatable elements remaining in the program file. 


NUM_SYM_ELTS 

Indicates the number of symbolic elements remaining in the program file. 


NUM_DELETED_ELTS 

Indicates the number of deleted elements of all types that were in the program file 

initially, and that were removed by this function. 


DEAD_SPACE 

Indicates the mass storage (in words) that was released by the function when 

STORAGE_TO_RELEASE has a value of ALL_BUT_INITIAL_RESERVE or 

ALL_STORAGE. Note that this value is not necessarily the same as the amount of 

dead space associated with the deleted elements and Object Module Entry Point 

Tables that were removed by this function. 


8–30 7830 9796–013

Notes: 


The following points apply to each item that returns the number of available entries in a 

table of contents: 

• For a standard program file, if a table is empty (current number of entries is zero), the 

value PCFP returns for the number of available entries in the table is also zero, even 

though in most cases entries can be added to the table. 

• For a standard program file, PCFP calculates the number of available entries by 

assuming that all tables that are empty at the end of PACK_PF remain empty. If an 

entry is added later to a table that is currently empty, the number of available entries 

in other tables may be significantly reduced. 

• For a large program file, all tables have fixed sizes and a fixed maximum number of 

entries. PCFP calculates the number of available entries by subtracting from the 

fixed maximum number the number of entries remaining in the table at the end of 

PACK_PF. 

• Some tables (for example, the COBOL procedure table) have variable-length entries. 

PCFP calculates the number of available entries by assuming entries of maximum 

size. 


The file identifier parameter names the file to be packed. The named file must be a 

program file on sector-addressable mass storage for which the calling program has both 

read and write privileges. See 2.3 for a full description of this parameter. 


The work area requirements of the two pack methods are described in this subsection. 

While deciding which method to select, you may want to review Appendix C. 

Subsections C.1, C.2, and C.3 describe PACK_PF performance and C.4 describes the 

contents of the file in case of a system or function failure. 

8.4.4.1. Standard Method Work Area Requirements 

The work area required by the PACK_PF standard method depends on the following: 

• Number of elements in the file 

• Number of procedure tables present 

• Number of procedure entries in each table 

• Size of the text to copy 

The standard method requires enough work area for one copy of the element table, two 

copies of each of the procedure tables, and the buffer that is used when copying 

element text. All of the information needed to calculate the standard method work area 

requirement can be obtained using the ACQ_BASIC_PF_INFO function, described in 6.1. 

7830 9796–013 8–31


The size of the work area required is calculated by the formula (350 + 10*T + 252*U + V 

+ MAX(V,W)), where 

T The initial number of elements in the file. This corresponds to the 

ACQ_BASIC_PF_INFO return value ELT_NUM_ENTRIES. 

U The initial number of procedure tables in the file (0 ≤ U ≤ 3). To calculate U, add 

one for each nonzero procedure table value returned by ACQ_BASIC_PF_INFO 

(MASM_PROC_NUM_ENTRIES, COBOL_PROC_NUM_ENTRIES, and 

FTN_PLS_PROC_NUM_ENTRIES). 

V The initial size of the procedure table entries in the file. It is calculated with the 

formula (8*X + 4*Y). X is the initial number of 8-word procedure entries in the 

COBOL procedure table. This corresponds to the ACQ_BASIC_PF_INFO return 

value NUM_8_WORD_COBOL_PROC_ENTRIES. Y is the sum of the initial 

number of procedure entries in the MASM procedure table, the initial number of 

procedure entries in the FORTRAN/PLUS procedure table, and the initial number 

of 4-word procedure entries in the COBOL procedure table. This corresponds to 

the sum of ACQ_BASIC_PF_INFO return values MASM_PROC_NUM_ENTRIES, 

FTN_PLS_PROC_NUM_ENTRIES, and 

NUM_4_WORD_COBOL_PROC_ENTRIES. One buffer this size is required for 

both pack steps. A second buffer this size is required for the first pack step 

MAX A function that selects the larger of the two values, V or W. 

W The I/O buffer that is used to copy element text during the second pack step. 

The function operates with any value greater than or equal to the minimum I/O 

buffer size (112 words). To maximize performance, W should be the same size in 

words as the largest element text associated with an undeleted element, but not 

greater than 64,512 words. This corresponds to the ACQ_BASIC_PF_INFO 

return value LARGEST_UNDELETED_TEXT_SIZE. Even if the file has very large 

elements, a buffer size of four 1,792-word tracks, or 7,168 words, usually 

achieves acceptable performance. A buffer size of eight 1,792-word tracks, or 

14,336 words, usually achieves good performance and is recommended. 

The standard method cannot be used unless sufficient work area is provided to satisfy 

the formula with the proper T, U, and V values and the minimum size for W. The 

performance of the function improves as W is increased to the size of the largest 

element text. Note that for some large program files, the formula may yield a value that 

is larger than the maximum possible work area of approximately 238,000 words. In this 

case, the file must be packed using the copy method. 

8–32 7830 9796–013


The following are five examples of program files and the work area that is required to 

pack each one using the standard method. Contrast these against the recommended 

work area requirements for the same five files using the copy method, described in 

8.4.4.2. 

1. A program file with 100 elements and one procedure table containing 35 procedure 

entries can be packed using the minimum I/O buffer size of 112 words when the 

minimum work area of 2,000 words is specified. 

2. A filled standard program file with 2,671 undeleted elements and three procedure 

tables each containing 861 4-word procedure entries can be packed using an I/O 

buffer size of 7,168 words when the maximum work area of 60,000 words is 

specified. 

3. A filled standard program file with 5,000 undeleted elements and no procedure 

tables can be packed using an I/O buffer size of 7,168 words when the maximum 

work area of 60,000 words is specified. 

4. A large program file with 22,300 elements and no procedure tables can be packed 

using an I/O buffer size of 14,336 words when the maximum possible work area of 

approximately 238,000 words is specified. 

5. A large program file with 10,000 elements and three procedure tables containing a 

total of approximately 17,000 procedure entries can be packed using an I/O buffer 

size of 64,512 words when the maximum possible work area of approximately 

238,000 words is specified. 

Program file examples 4 and 5 have tables that are greater than 65,436 words, so you 

would specify PACK_METHOD as STANDARD or COPY_IF_NECESSARY to use the 

standard method. A value of DEFAULT selects the copy method, even if sufficient work 

area is provided. 

8.4.4.2. Copy Method Work Area Requirements 

The work area required by the PACK_PF copy method is based on the requirements for 

the two main PCFP functions that it calls: COPY_ELT and COPY_RAF_RAF. 

Unlike the standard method where sufficient work area must be provided to satisfy the 

formula, the copy method can be used to pack any format program file of any size 

whenever there is a minimum work area of 4,570 words. 

However, to maximize performance it is important to use the formulas described in this 

subsection to determine the amount of work area to specify. 

The work area requirements for the first copy method step are based on the COPY_ELT 

work area requirements and are completely described in 7.1.6. The work area 

requirements for the second copy method step are based on the COPY_RAF_RAF work 

area requirements and are completely described in 5.1.5. After calculating the work area 

requirements for both functions, use the larger of the two values to maximize 

performance, but not more than the maximum possible value of approximately 238,000. 

7830 9796–013 8–33


The first copy method step calls the COPY_ELT function to copy undeleted elements to 

the temporary file. This work area formula uses the same abbreviations as described in 

7.1.6. All of the information needed to calculate the work area requirement can be 

obtained using the ACQ_BASIC_PF_INFO function, described in 6.1. The work area 

required is calculated by the formula 215 + S + D + I + C, where 

215 The fixed function requirement. This is the COPY_ELT requirement of 125 plus 90 

words of additional overhead. 

S The program file buffer size. This is 252 + 10*J, where J is the initial number of 

elements in the program file. This corresponds to the ACQ_BASIC_PF_INFO 

return value ELT_NUM_ENTRIES. 

D The temporary file buffer size. This is 252 + 10*L, where L is the number of 

undeleted elements in the program file. This corresponds to the difference 

between ACQ_BASIC_PF_INFO return values ELT_NUM_ENTRIES and 

NUM_DELETED_ENTRIES. 

I The I/O buffer size. The minimum I/O buffer size is 896 words. To maximize 

performance, I should be the size in words of the largest element text associated 

with an undeleted element, but not more than 64,512 words. This corresponds to 

the ACQ_BASIC_PF_INFO return value LARGEST_UNDELETED_TEXT_SIZE. 

Even if the file has very large elements, a buffer size of four 1,792-word tracks, or 

7,168 words, usually achieves acceptable performance. A buffer size of eight 

1,792-word tracks, or 14,336 words, usually achieves good performance and is 

recommended. 

C The procedure table copy buffer size. This is 3 + 3*N, where N is the number of 

undeleted elements with associated procedure table entries. This corresponds to 

the ACQ_BASIC_PF_INFO return value NUM_UNDELETED_PROC_ELTS. 

To maximize performance, ensure that the work area recommended for D (temporary file 

buffer) and I (I/O buffer) is available. If possible, provide the work area recommended for 

C (procedure table copy buffer). If necessary, the work area for S (program file buffer) 

can be reduced to its minimum of 252 without too much impact on function 

performance. 

Note: C in the copy method formula is based on the number of elements that have 

associated procedure table entries, while V in the standard method formula (8.4.4.1) is 

based on the number of procedure table entries. 

8–34 7830 9796–013


The second copy method step calls the COPY_RAF_RAF function to copy the temporary 

file back to the program file. This work area formula uses the same abbreviations as in 

5.1.5. The work area required is calculated by the formula 870 + 3700*N, where 

870 The fixed function requirement. This is the COPY_RAF_RAF requirement (K) of 

800 for a temporary source file plus 70 words of additional overhead. 

N The number of track size buffers to allocate. The minimum value is 1. Acceptable 

performance can usually be achieved with a value of 4. The recommended value 

is 8. 

This formula produces a COPY_RAF_RAF minimum work area requirement value of 

4,570, an acceptable value of 15,670, and a recommended value of 30,470. Some 

additional performance improvement can be expected with the maximum N value of 16, 

yielding a work area value of 60,070. 

Generally, the work area recommended for the copy method is larger than the work area 

recommended for the standard method (8.4.4.1). This is particularly true for small files. 

The recommended value of 30,470 for the second copy method step is usually large 

enough for a file containing approximately 750 undeleted elements. For files with more 

elements, the recommended value for the first copy method step is usually larger. 

For the five program file examples in 8.4.4.1, the following work area sizes would be 

recommended to achieve good performance using the copy method: 

1. For the file with 100 elements and 35 procedures, the COPY_RAF_RAF 

recommended value of 30,470 applies. 

2. For the filled standard program file with 2,671 undeleted elements, assuming 100 

are procedure elements, the COPY_ELT recommended value of 68,778 is calculated 

from the formula. Note that reducing S in the COPY_ELT formula to its minimum 

should not seriously affect performance and reduces the total work area value to 

42,068. 

3. For a filled standard program file with 5,000 undeleted elements and with no 

procedure tables, the COPY_ELT recommended value of 115,058 is calculated from 

the formula. Reducing S to its minimum reduces the total work area value to 

65,058. 

4. For the large program file with 22,300 undeleted elements and with no procedure 

tables, the maximum possible work area of 238,000 is calculated from the 

COPY_ELT formula, even by reducing S to its minimum. 

5. For the large program file with 10,000 undeleted elements, assuming 1,000 are 

procedure elements, the COPY_ELT recommended value of 218,058 is calculated 

from the formula. Reducing S to its minimum reduces the total work area value to 

118,058. 

7830 9796–013 8–35


8.5. Create Program File Entry Point Table 

(PREP_PF) 

The PREP_PF function builds a relocatable or an object-module entry point table in a 

program file. This function corresponds to the FURPUR @PREP command. 

This function handles the two entry point tables differently. The process of building a 

relocatable entry point table destroys any existing relocatable entry point table. Thus the 

table is always rebuilt completely. On the other hand, the process of building the 

object-module entry point table always consists of adding to the existing object 

module-entry point table. 

When building the relocatable entry point table, this function always selects the starting 

address of the table such that the table occupies the minimum space needed to 

accommodate all of the relocatable entry points. In this way, this function differs from 

the FURPUR @PREP command, which always starts this table at the system defined 

starting address. The PCFP PREP_PF function may be able to successfully build a 

relocatable entry point table for some program files where the FURPUR @PREP 

command returns an error. 


• Creates a relocatable entry point table, an object-module entry point table, or both 

tables. 

• Creates a relocatable entry point table even if one already exists. (If this option is not 

specified, this function does not rebuild the relocatable entry point table when one 

already exists, even though the calling program specifically calls for the creation of a 

relocatable entry point table.) 

This function exclusively assigns the program file upon which it operates. 


The PREP_PF function has the following parameters, each of which is described in the 




• Work Area 

8–36 7830 9796–013



The structure of the PREP_PF function packet is defined in element FP$PREPPF. See 

Figure 8–5. 

GENERIC PART 

0 a EP_TYPE 

1 REL_EP_CNT DUP_REL_EP_CNT 

2 OM_EP_CNT 


a = OVERWRITE_OLD_EP_TABLE 

Figure 8–5. PREP_PF Function Packet Items 

Indicates if this function rebuilds the relocatable entry point table when a table exists 

previously. 


EP_TYPE 

Indicates which entry point tables this function builds. 


REL_EP = 1 

Creates only the relocatable entry point table. 

OM_EP = 2 

Creates only the object-module entry point table. 

BOTH = 3 

REL_EP_CNT 

Creates both relocatable and object-module entry point tables. 

Indicates the number of entry points within all of the relocatable elements that the 

program file contains. All of these are included in the relocatable entry point table. 

This value is zero if the calling program did not request building of the relocatable 

entry point table. 


7830 9796–013 8–37


DUP_REL_EP_CNT 

Indicates the number of entry points in all of the relocatable elements within the 

program file having names duplicating other entry points within the program file. 

This value is zero if the calling program did not request building of the relocatable 

entry point table. 


OM_EP_CNT 

Indicates the number of entry points within all of the object modules that are in the 

OM entry point table following the completion of the PREP_PF function. 



The file identifier parameter names the file to be prepped. The named file must be a 

program file on sector-addressable mass storage for which the calling program has both 

read and write privileges. See 2.3 for a full description of this parameter. 

8–38 7830 9796–013



The calling program must supply a work area of 1,500 words if only the object-module 

entry point table is built. If the calling program requests the creation of the relocatable 

entry point table, either by itself or in conjunction with the object-module entry point 

table, the calling program must supply a work area of at least 1,500 or (600 + 8*N) 

words, where N is the number of relocatable entry points in the program file. 

The maximum defined work area of 26,000 words is adequate to handle a standard size 

relocatable entry point table containing up to 3,101 relocatable entry points. However, 

when no procedure tables are present in a standard program file the relocatable entry 

point table can be expanded to contain up to 5,789 relocatable entry points, which would 

require a work area of 47,000 words. Further expansion into unused element table 

entries allows a theoretical expansion of the relocatable entry point table to a maximum 

of 12,460 relocatable entry points, which would require a work area of 100,000 words. A 

large program file has a fixed maximum of 20,125 relocatable entry points, which would 

require a work area of 162,000 words. 

The specified WORK_AREA_SIZE should not exceed approximately 227,000 words. This 

is the approximate maximum size that can be specified for this function, where the 

minimum relative address is MIN_DATA_ADDR_WITH_LINK and the maximum relative 

address is MAX_DATA_ADDR, as contained in the copy/include element FP$DEFS. 

If error FP_ERR_SMALL_PREP_PF_WORK_AREA is returned, this indicates that the 

specified WORK_AREA_SIZE is not sufficient for the number of relocatable entry points 

in the file. The number of relocatable entry points is returned in item 

AUX_ERROR_CODE in the generic part of the function packet (see 2.4.1). You can use 

AUX_ERROR_CODE for the value N in the formula (600 + 8*N). This calculates the 

WORK_AREA_SIZE required for this file. Call the PREP_PF function again with this 

WORK_AREA_SIZE value. 

If error FP_ERR_TOC_SPACE_TOO_SMALL is returned, this indicates that the size of the 

program file relocatable element entry point table is not sufficient for the number of 

relocatable entry points in the file. A relocatable element entry point table cannot be 

built for this file unless some of the relocatable elements are deleted with the PCFP 

DELETE_ELT function or the FURPUR @DELETE,R command. 

7830 9796–013 8–39


8–40 7830 9796–013

Section 9 

Erasing and Deleting Files 

This section describes the following PCFP functions that erase and delete files: 

• Erase RAF (ERASE_RAF) 

• Delete File (DELETE_FILE) 

9.1. Erase RAF (ERASE_RAF) 

The ERASE_RAF function releases mass storage from a random-access file. It can also 

zero-fill the file storage it releases or the file storage it does not release. 

This function operates on cataloged and temporary, sector-addressable, and 

word-addressable mass storage files. This function exclusively assigns the file it 

operates on. 

This function has the following options: 

• Release the mass storage associated with the file according to one of the following 

schemes: 

− Do not release any mass storage. 

− Release only mass storage not included in the initial reserve of the file. 

− Release all mass storage including the initial reserve. 

Note: Select this third alternative to guarantee that a file is entirely empty. The other 

two alternatives might leave residual data in the file, which other PCFP functions might 

interpret as valid data. 

• If mass storage is released from the file, zero-fill it before it is released or do not 

change it before it is released. 

• If mass storage is retained in the file, zero-fill the first track (1792 words) of the file 

and up to the lesser of the highest track written and the highest track retained or 

zero-fill only the first sector (28 words) of the file. 

• If the first track of the file is retained and if it is the only track to be zero-filled, 

zero-fill it unconditionally or zero-fill it only if it was previously written. 

7830 9796–013 9–1


The following are considerations when ERASE_RAF operates on word-addressable files: 

• The option to release only mass storage not included in the initial reserve is not 

available. If it is specified, all mass storage including the initial reserve is released. 

• The option to zero-fill retained mass storage will zero-fill to the larger of highest track 

written and initial reserve. 


The ERASE_RAF function has the following parameters, each of which is described in 




• Work Area 


The structure of the ERASE_RAF function packet is defined in element FP$ERSRAF. 


GENERIC PART 

0 a b c STORAGE_TO_RELEASE 

1 STORAGE_RELEASED 


Figure 9–1. ERASE_RAF Function Packet Items 

a = ZERO_RELEASED_STORAGE 

When TRUE, indicates that mass storage is to be zero-filled before it is released. 

When FALSE, indicates that mass storage is not changed before it is released. This 

item is ignored if no mass storage is released. 


9–2 7830 9796–013

= ZERO_RETAINED_STORAGE 


When TRUE, indicates that the first track of retained mass storage is to be 

zero-filled. For sector-addressable files, retained mass storage is zero-filled up to the 

lesser of highest track written and highest track retained. For word-addressable 

files, retained mass storage is zero-filled up to the greater of the highest track 

written and the initial reserve. When FALSE, indicates that only the first sector of 

retained mass storage is to be zero-filled. This item is ignored if no mass storage is 

retained. 


c = ZERO_FIRST_TRACK_ONLY_IF_WRITTEN 

When only the first track or the first sector of retained mass storage is to be 

zero-filled, this item indicates if PCFP should perform additional checks before 

writing to the file. When TRUE, the first track or the first sector is zero-filled only if 

any part of the first track was previously written. When FALSE, the first track or the 

first sector is always zero-filled. This item is ignored if no mass storage is retained or 

if retained mass storage is to be zeroed beyond the first track. 



Indicates to what extent this function releases mass storage from the file. 


NONE = 0 

Releases no mass storage from the file. 


For sector-addressable files, release all mass storage beyond the initial reserve 

of the file. For word-addressable files, release all mass storage from the file 

including the initial reserve. 


Releases all mass storage from the file, including the initial reserve. 

STORAGE_RELEASED 

Indicates the number of words of mass storage that this function actually released. 


7830 9796–013 9–3



The file identifier parameter names the file to be erased. The named file must be a mass 

storage file for which the calling program has write privileges. If the 

ZERO_FIRST_TRACK_ONLY_IF_WRITTEN item is TRUE, the calling program also needs 

to have read privileges for the file. See 2.3 for a description of this parameter. 


The ERASE_RAF function requires a work area of 1,000 words. 

9.2. Delete File (DELETE_FILE) 

This DELETE_FILE function deletes a specified file. It operates on all file types. It 

handles both cataloged and temporary files. 


• Does not perform the deletion if the file is assigned by other users. 

• Zero-fills all mass storage before the file is deleted. This option is applicable only for 

mass storage files. 

This function can operate on a mass storage file that is unloaded, unless the option to 

zero-fill the file is selected. If that option is selected, the function causes the file to be 

rolled in. 


The DELETE_FILE function has the following parameters, each of which is described in 




• Work Area 

9–4 7830 9796–013



The structure of the DELETE_FILE function packet is defined in element FP$DELFIL. 


0 a b 



GENERIC PART 

Figure 9–2. DELETE_FILE Function Packet Items 

Indicates whether PCFP must exclusively assign the file to be deleted prior to 

deleting it to ensure that no other runs have the file assigned. 


b = ZERO_RELEASED_STORAGE 

Indicates if PCFP zero-fills all mass storage in the file prior to deleting the file. The 

calling program can set this item to TRUE only if it also sets EXCLUSIVE_ASSIGN = 

TRUE. PCFP ignores this item if the file is not a mass storage file. If this item is 

TRUE and the file is unloaded, PCFP rolls in the file before deletion. If this item is 

FALSE and the file is unloaded, PCFP deletes the file without rolling it in. 



The file identifier parameter names the file to be deleted. The calling program must have 

write privileges for this file. See 2.3 for a complete description of this parameter. 


The DELETE_FILE function requires a work area of 1,000 words. 

7830 9796–013 9–5


9–6 7830 9796–013

Section 10 

Positioning and Closing Tape Files 

This section describes the following functions that reposition and close tape files. 

• Move SAF (MOVE_SAF) 

• Close SAF (CLOSE_SAF) 

10.1. Move SAF (MOVE_SAF) 

The MOVE_SAF function repositions a tape file forward or backward through a specified 

number of logical files stored on the tape file. It can also reposition a tape file to its 

physical start (load point) or its logical end. For tape subsystems that support fast tape 

access, MOVE_SAF can use a previously saved block-id to quickly reposition a tape file. 

The MOVE_SAF function returns the following information: 

• Identifier of the current volume (reel or cartridge) after the move 

• The volume-relative position of the logical file to which PCFP positioned the tape file 

• The block-id that corresponds to the final tape position after the move 

• The number of logical files through which PCFP actually moved the tape file 

• The number of swaps PCFP performed 

The MOVE_SAF function has the following options: 

• Move the tape file in one of the following ways: 

− Forward N logical files from the current position (N must be ≥ 0) 

− Backward N logical files from the current position (N must be > 0) 

− To the logical end of the tape file (immediately beyond the last logical file on the 

tape file) 

− To the physical start of the tape file (that is, rewind the tape file) 

− To a previously saved block-id 

• Moving backward is not allowed for quarter-inch-cartridge tape files. 

7830 9796–013 10–1


• Either limits the move to the current volume (that is, does not perform volume 

swaps) or moves through multiple volumes if necessary (that is, performs volume 

swaps, if necessary). When a tape is moved backwards, only the first alternative is 

allowed. 

If the calling program request indicates a move to logical end of file, and also limits 

the move to the current volume, PCFP returns an error if the logical end of the file is 

not on the current volume. 

• If PCFP attempts to swap beyond the last volume of the file (because the physical 

end of the last volume is reached before the logical end of the tape file), it can take 

one of the following actions: 

− Return with error status. (In this case, the tape file remains positioned at the 

physical end of the last volume.) 

− Dynamically extend the tape file. (PCFP solicits the operator for the identifier of 

the next volume to allow processing of the remainder of the tape file.) 

• At the end of the move, PCFP can position the tape file either at the physical start or 

at the physical end of the logical file to which the tape file was moved. (The second 

alternative corresponds to the action of the FURPUR @MOVE,B command, and is 

allowed only when moving backward from the current position. The first alternative 

causes the tape file to be positioned ready for a copy operation, which is the action 

usually desired.) 

• Return the block-id that corresponds to the final position after the move. The 

block-id can be saved and used later to quickly position the tape to the same 

position. 

The following options apply only when moving to the start of (rewinding) a tape file: 

• Rewinds to the start of the first volume of the file, or only rewinds to the start of the 

current volume. 

• Rewinds with or without interlock. (You cannot use a tape file rewound with 

interlock again unless you free and re-assign it.) 

This function returns the warning FP_WARN_AT_SAF_END (11) whenever it positions 

the tape file at its logical end. It returns the warning FP_WARN_AT_VOL_START (13) 

whenever it positions the tape file at the start of any volume of the file. 


The MOVE_SAF function has the following parameters, each of which is described in the 




• Work Area 

10–2 7830 9796–013



The structure of the MOVE_SAF function packet is defined in element FP$MOVSAF. 


Note: Figure 10–1 shows the new format function packet that is used when 

INTERFACE_LEVEL has value of at least FP_INTERFACE_LEVEL_3. A new function 

packet definition must be used when specifying the new interface level. 

• For C users, the definition name is fp_move_saf_3_type and the corresponding 

function prototype name is _fp_move_saf_3. 

• For COBOL users, the definition name is FP-MOVE-SAF-3. 

• For FORTRAN users, the definition name is FP$MOVSAF3. 

If you modify an existing MOVE_SAF function to use an INTERFACE_LEVEL value of 

FP_INTERFACE_LEVEL_3, you must also modify the return function packet definition to 

use the new definition name. For compatibility, the previous definition names are 

unchanged and describe the interface level 1 and 2 function packets. The format of the 

interface level 1 and 2 function packets is described in the previous definitions. 

0 a b c d 

GENERIC PART 

1 TYPE_OF_MOVE ON_END_OF_FILE 

2 MOVE_NUM 

3 NUM_FILES_MOVED 


5 VOL_ID 

6 VOL_ID NUM_SWAPS 

7 MOVE_BLOCK_ID 

8 BLOCK_ID 

Figure 10–1. MOVE_SAF Function Packet Items 

7830 9796–013 10–3








− RETURN_BLOCK_ID must be FALSE 

− TYPE_OF_MOVE cannot be set to TO_BLOCK_ID 

− MOVE_BLOCK_ID is ignored 

− BLOCK_ID is not returned 

− The function packet has a format different than that shown in Figure 10–1 

• If this item is set to FP_INTERFACE_LEVEL_2, the function packet has a format 

different than that shown in Figure 10–1 


a = CURRENT_VOL_ONLY 

If the calling program sets this item to TRUE, the movement done by this function is 

confined to the currently mounted volume. Swapping of volumes cannot occur. If 

the calling program sets this item to TRUE and also sets TYPE_OF_MOVE = 

TO_SAF_START (rewind), this function positions the tape to the start of the current 

volume of the file. See Table 10–1 in 10.1.3 to determine the effect of this item in 

combination with other items. 


b = POSITION_AT_END_OF_LOG_FILE 

If the calling program sets this item to TRUE, this function positions the tape file at 

the physical end of the logical file to which it moved the tape. If the calling program 

sets this item to FALSE, this function positions the tape file at the physical start of 

the logical file to which it moved the tape. The calling program can set this item to 

TRUE only if it also set TYPE_OF_MOVE = BACKWARD. See Table 10–1 in 10.1.3 

to determine the effect of this item in combination with other items. 


c = INTERLOCK 

If the calling program sets this item to TRUE, PCFP rewinds the tape file with 

interlock. The calling program can set this item to TRUE only if it also set 

TYPE_OF_MOVE = TO_SAF_START. 


10–4 7830 9796–013

d = RETURN_BLOCK_ID 


If TRUE, PCFP returns the block-id that corresponds to the final position after the 

move. This item can be TRUE only if INTERFACE_LEVEL has a value of at least 



TYPE_OF_MOVE 

Indicates the type of tape movement PCFP performs. See Table 10–1 in 10.1.3 to 

determine the effect of this item in combination with other items. 

Data Type: value list 

FORWARD = 0 

Indicates that PCFP moves the tape file forward from its current position. 

MOVE_NUM indicates the number of logical files through which PCFP moves 

the tape. 

BACKWARD = 1 

Indicates that PCFP moves the tape file backward from its current position. 

MOVE_NUM, which must be greater than zero, indicates the number of logical 

files through which PCFP moves the tape. 

TO_SAF_END = 2 

Indicates that PCFP positions the tape file at its logical end. At this position, you 

can extend the tape file by copying another logical file to it. (The logical end of a 

tape file is the position immediately following the last logical file on the tape.) 

TO_SAF_START = 3 

Indicates that PCFP positions the tape file at its physical beginning. The item 

CURRENT_VOL_ONLY controls whether PCFP positions the tape at the start of 

either the current volume or the first volume. 

TO_BLOCK_ID = 4 

Indicates that PCFP should position the tape with the fast tape access Locate 

Block (LBLK$) I/O function to the block-id indicated in MOVE_BLOCK_ID. This 

value can be specified only if INTERFACE_LEVEL has a value of at least 

FP_INTERFACE_LEVEL_2. See 10.1.6 for special considerations relating to this 

type of tape positioning. 

7830 9796–013 10–5


ON_END_OF_FILE 

Indicates what action PCFP takes if it encounters the physical end of the last volume 

of the tape file before the logical end of the file. 


RTN_ERROR = 0 

Indicates that PCFP positions the file at the physical end of the last volume, and 

returns an error status to the calling program. 


MOVE_NUM 



limited to 








Indicates the number of logical files through which PCFP moves the tape file. If the 

calling program sets TYPE_OF_MOVE = TO_SAF_END, TO_SAF_START, or 

TO_BLOCK_ID, it must set this item to zero. If the calling program sets 

TYPE_OF_MOVE = BACKWARD, it must set this item to a value greater than zero. 


NUM_FILES_MOVED 

This item gives the number of logical files between the original tape position and the 

new tape position (either forward or backward). This item is unknown and is set to 

zero under the following conditions: 

• If TYPE_OF_MOVE = TO_SAF_START and CURRENT_VOL_ONLY = FALSE 

• If TYPE_OF_MOVE = TO_SAF_START and if the tape has been positioned using 

the Locate Block (LBLK$) I/O function 

• If TYPE_OF_MOVE = TO_BLOCK_ID 


10–6 7830 9796–013



Indicates the volume-relative position of the logical file to which this function 

positioned the tape file. This item is unknown and is set to zero under the following 

conditions: 

VOL_ID 

• If TYPE_OF_MOVE = TO_BLOCK_ID 

• If the tape is unlabeled and has been positioned using the Locate Block (LBLK$) 

I/O function, and if this MOVE_SAF function did not position the tape to its 

physical start (load point) 


Indicates the identifier of the volume to which this function positioned the tape file. 

If the tape file was assigned with a BLANK volume identifier and if the tape file has 

not been previously read or written and if the TYPE_OF_MOVE specified is 

TO_SAF_START, then a null value is returned for this item. 

Data Type: characters (6), returned 

NUM_SWAPS 

This item gives the number of volume swaps PCFP did during execution of the 

function. The value PCFP returns in this item is meaningful only if the calling 

program set TYPE_OF_MOVE = FORWARD or TO_SAF_END, and 

CURRENT_VOL_ONLY = FALSE. 


MOVE_BLOCK_ID 

Indicates the block-id to use for fast tape access positioning when TYPE_OF_MOVE 

= TO_BLOCK_ID. This item must be zero for all other TYPE_OF_MOVE values. This 

item is ignored if INTERFACE_LEVEL has a value of FP_INTERFACE_LEVEL_1. 


7830 9796–013 10–7


BLOCK_ID 

Indicates the block-id that corresponds to the final position after the move. This item 



• Negative one (-1) if fast tape access is not supported for the tape file 

• Negative two (-2) if this is a labeled tape and if the final position is at the logical 

end of the tape 


A valid block-id can be saved and used later with TYPE_OF_MOVE = TO_BLOCK_ID 

to quickly move to this position. This item can be returned only if 


Data Type: signed integer, returned 

10–8 7830 9796–013


10.1.3. Actions Performed by the MOVE_SAF Function 

TYPE_OF_MOVE 

Table 10–1 indicates the actions taken by PCFP depending on the values to which the 

calling program sets the items TYPE_OF_MOVE, CURRENT_VOL_ONLY, and 

POSITION_AT_END_OF_LOG_FILE. 

Table 10–1. Actions Performed by MOVE_SAF Function 

CURRENT_ 

VOL_ONLY 

POSITION_AT_END_ 

OF_LOG_FILE 

Action Taken by PCFP 

FORWARD false false Move forward past N EOF marks; swap 

volumes as necessary. 

false true Error—illegal combination of options. 

true false Move forward past N EOF marks; error if a 

swap is necessary. 

true true Error—illegal combination of options. 

BACKWARD false false Error—illegal combination of options. 


true false Move backward past N+1 EOF marks; error if 

start of volume is encountered. Next, move 

forward past one EOF mark. 

true true Move backward past N EOF marks; error if 

start of volume is encountered. 

TO_SAF_END false false Move forward until logical-end indicator is 

encountered; swap volumes as necessary. 

false true Error — illegal combination of options. 

true false Move forward until logical-end indicator is 

encountered; error if swap is required. 


TO_SAF_START false false Issue ER TINTL$, which mounts the first 

volume of the file. The current position is set 

to the start of that volume. 


true false Issue rewind I/O request, which sets the 

current position to the start of the current 

volume. 


TO_BLOCK_ID false false Error—illegal combination of options. 


true false Use LBLK$ to position to MOVE_BLOCK_ID. 


7830 9796–013 10–9



The file identifier parameter names the file to be positioned. The named file must be a 

tape file for which the calling program has read privileges. See 2.3 for a complete 

description of this parameter. 


The MOVE_SAF function requires a work area of 1,000 words. 

10.1.6. Fast Tape Access Considerations 

Fast tape access features are available in all of the PCFP tape functions (CLOSE_SAF, 

COPY_RAF_SAF, COPY_SAF_RAF, COPY_SAF_SAF, and MOVE_SAF). All of these 

functions allow the caller to set the function packet RETURN_BLOCK_ID = TRUE to 

return a block-id that identifies the position of the tape. Later, the MOVE_SAF function 

can be called with TYPE_OF_MOVE = TO_BLOCK_ID, and MOVE_BLOCK_ID set to the 

previously returned block-id. The Locate Block (LBLK$) I/O function is used by PCFP to 

quickly position the tape to the saved location. 

The following are important considerations related to fast tape access operations: 

• Fast tape access is available on all supported half-inch cartridge tape subsystems. 

• To ensure correct operations, block-ids should always be saved with their associated 

volume-ids. 

• Special privileges are required to perform the LBLK$ I/O function. If the MOVE_SAF 

function is called with TYPE_OF_MOVE = TO_BLOCK_ID and the caller does not 

have the required privileges, an error fp_err_no_locate_block_priv (error code 2346) is 

returned. 

− For systems with Fundamental Security (SENTRY_CONTROL = FALSE), the 

caller must be running under the overhead account or the security officer 

account or must have SYS$*DLOC$ assigned to the run with the correct read 

and write keys. 

− For systems with Security Option 1, 2, or 3 (SENTRY_CONTROL = TRUE), the 

special privileges bypass_tape_hdr1_read_checks (SSBHDR1RDCHK) and 

bypass_object_reuse (SSBYOBJREUSE) are required. 

• No special privilege is required to return block-id for any of the PCFP tape functions. 

• When the MOVE_SAF function is called with TYPE_OF_MOVE = TO_BLOCK_ID, 

there is no tape position validation, as there is with the other TYPE_OF_MOVE 

values. It is, therefore, important to ensure that the correct volume is mounted 

when performing the TYPE_OF_MOVE = TO_BLOCK_ID 

10–10 7830 9796–013


• Once an LBLK$ I/O function has been performed, special conditions are set by the 

Exec. These conditions remain in effect until the tape is returned to its physical start 

(load point). Typically, the MOVE_SAF function is called with TYPE_OF_MOVE = 

TO_SAF_START to move a tape to load point. The following are special conditions 

and how they affect PCFP operations: 

− The tape becomes write inhibited. An attempt to write to the tape using the 

COPY_RAF_SAF, COPY_SAF_SAF or CLOSE_SAF functions results in an 

fp_err_locate_block_done error (error code 2344). The tape can be read using 

the COPY_SAF_RAF and COPY_SAF_SAF functions. 

− Once a tape is positioned with LBLK$, it is not possible to determine exactly 

what precedes this position. The relative position of this file on the tape is, 

therefore, unknown and LOGICAL_FILE_POSITION is returned as zero on the 

ACQ_FILE_INFO and ACQ_FILE_LIST functions (see 3.1.4.4), on the 

COPY_SAF_RAF and COPY_SAF_SAF functions (see 5.3.5), and on the 

MOVE_SAF function (see 10.1.2). 

− Tape labeling is disabled if this is a labeled tape. 

− If the tape is labeled, the only MOVE_SAF function TYPE_OF_MOVE values 

allowed are TO_SAF_START and TO_BLOCK_ID. Other TYPE_OF_MOVE values 

result in an fp_err_locate_block_done error (error code 2344). 

− If the tape is unlabeled, all MOVE_SAF function TYPE_OF_MOVE values can be 

used. However, until the tape is returned to load point, the 

LOGICAL_FILE_POSITION is unknown and is set to zero. 

− If the tape is labeled, once a file has been read with a COPY_SAF_RAF or 

COPY_SAF_SAF function, it must be repositioned with a MOVE_SAF function 

with TYPE_OF_MOVE = TO_BLOCK_ID before another file on the tape can be 

read. 

• In most cases LBLK$ positioning is much faster than the equivalent forward space 

file (FSF$) and back space file (BSF$) I/O functions used with the MOVE_SAF 

function TYPE_OF_MOVE = FORWARD, BACKWARD, and TO_SAF_END. 

However, for some older tape equipment types, if the destination of the LBLK$ is 

close to the current position of the tape, the LBLK$ may actually be slower than the 

equivalent FSF$/BSF$ I/O functions. In some extreme cases, the LBLK$ may 

actually cause the tape to rewind to load point and search forward slowly. The tape 

equipment types that can encounter this performance problem are styles 5073-02, 

5073-03, 5073-SSI, 5073-LSI and USR-5073-xxx, commonly identified as U40 tape 

equipment. 

7830 9796–013 10–11


10.2. Close SAF (CLOSE_SAF) 

The CLOSE_SAF function is primarily intended for use with unlabeled tapes: 

• When the caller sets the COPY_RAF_SAF and COPY_SAF_SAF function packet item 

OMIT_LOG_END_MARK to TRUE, the CLOSE_SAF function must be used to write a 

logical end sequence on a tape when copy operations are complete. This is a 

technique for improving performance when writing files to an unlabeled destination 

tape. If the CLOSE_SAF function is followed by another COPY_RAF_SAF or 

COPY_SAF_SAF function, the logical end sequence will be overwritten and another 

CLOSE_SAF function will be required. 

Note: The failure to write a logical end sequence on a tape can result in a tape loss 

of position and an unrecoverable I/O error when the last file on the tape is read. 

• When the caller sets the COPY_RAF_SAF and COPY_SAF_SAF function packet item 

OMIT_LOG_END_MARK to FALSE, the CLOSE_SAF function is not required. 

The CLOSE_SAF function provides the option of returning the block-id of the logical end 

sequence. It should be noted that this block-id cannot be used later with the 

MOVE_SAF function to position the tape to write additional files on the tape. This is 

because the tape becomes write-inhibited following the locate block (LBLK$) I/O 

function, as described in 10.1.6. 

The CLOSE_SAF function provides the option of ensuring that all data has been written 

from the tape buffer to the physical tape after writing the logical end sequence. This is 

known as synchronizing the host system and the tape drive and is normally done at the 

end of each tape file by the Exec or by the tape subsystem. However, when the 

BUFTAP buffered-write mode is enabled for the tape, the Exec improves tape write 

performance by inhibiting this synchronization. When you select this option and BUFTAP 

is enabled, unlabeled and labeled tapes operate as follows: 

• For unlabeled tapes, this option is ignored since the logical end sequence written 

includes a move backward (MB$) I/O function that causes the tape subsystem to 

implicitly perform synchronization. 

• For labeled tapes, this option performs synchronization after the logical end 

sequence is written. However, the write end-of-file (WEF$) I/O function used to 

write the logical end sequence creates a null file at the end of the tape. A null file 

contains Exec tape labeling system header label blocks and trailer label blocks but no 

user data blocks. If a null file is not desired at the end of the tape, then the last 

COPY_RAF_SAF or COPY_SAF_SAF function to write to the tape should set the 

function packet item SYNCHRONIZE to TRUE, as described in 5.2.2 and 5.4.2, 

respectively, and the CLOSE_SAF function should not be called. 

10–12 7830 9796–013



The CLOSE_SAF function has the following parameters, each of which is described in 




• Work Area 


The structure of the CLOSE_SAF function packet is defined in element FP$CLSSAF. 


GENERIC PART 

0 FORMAT a b 

1 BLOCK_ID 



Figure 10–2. CLOSE_SAF Function Packet Items 




If this item is set to FP_INTERFACE_LEVEL_1, then 

• RETURN_BLOCK_ID must be FALSE. 

• SYNCHRONIZE must be FALSE. 

• The item BLOCK_ID is not returned. 


FORMAT 

Indicates the format of the logical-end mark PCFP writes to the tape file. 


FURPUR = 1 

This is currently the only value to which the calling program can set this item. 

7830 9796–013 10–13


a = RETURN_BLOCK_ID 

If TRUE, PCFP returns the block-id that corresponds to the position of the logical end 

sequence. This item can be TRUE only if INTERFACE_LEVEL has a value of at least 



b = SYNCHRONIZE 


end sequence, ensure that all buffered data has been successfully written to tape. If 

necessary, a synchronize (FSAFE$) I/O function is issued. This item is ignored if the 

buffered-write mode is BUFOFF, BUFON, or BUFFIL. This item is also ignored for 

unlabeled tapes. In these cases, the system and the tape are implicitly synchronized 

by the Exec or by the tape subsystem. This item can be TRUE only if 



BLOCK_ID 

Indicates the block-id that corresponds to the position of the logical end sequence. 

This item can have the following values: 

• Zero when the RETURN_BLOCK_ID item is FALSE 

• Negative one (-1) if fast tape access is not supported for the tape file 


This item can be returned only if INTERFACE_LEVEL has a value of at least 


Data Type: signed integer, returned 


The file identifier parameter names the file to be closed. The named file must be a tape 

file for which the calling program has read and write privileges. See 2.3 for a complete 

description of this parameter. 


The CLOSE_SAF function requires a work area of 1,000 words. 

10–14 7830 9796–013

Section 11 

Using PCFP with C 

This section contains information about using PCFP with programs written in C. 

11.1. Include Considerations 

All PCFP include elements used by C programs have a version name of H, and all have 

names beginning with the characters fp$. These elements are all contained in the file 

SYS$LIB$*PROC$, which is searched automatically by the UC compiler. Thus, it is not 

necessary to code the file name in the #include statement. The recommended form for 

coding #include statements for PCFP definition elements is: 

#include 

where xxxxxxxxx represents the specific part of the element name. 

The following PCFP elements must be included in most or all programs that call PCFP. 

Prior to these elements, your program must also include the common standard header, 

stddef.h. 

• fp$defs.h 

This element contains definitions of constants, enumeration lists, and structures that 

are used by all PCFP functions. You must include this element in every program that 

calls PCFP before any other PCFP element. 

• fp$errors.h 

This element contains constant definitions of error and warning codes that PCFP can 

return. This element is optional; you are required to include it in your program only if 

your program refers to specific error and warning codes by their defined names. 

• fp$file$id.h 

This element contains the typedef definition of the file identifier structure, which is 

used as a parameter by most PCFP functions. You must include this element in any 

program that calls a PCFP function that has one or more file identifier parameters. 

• fp$generic.h 

This element contains the typedef definition of the generic part of the PCFP function 

packet. You must include this element in every program that calls a PCFP function 

before any element that defines a specific function packet. 

7830 9796–013 11–1


• fp$rtn$info.h 

This element contains the typedef definition of the return-information portion of the 

PCFP function packet. This portion of the function packet exists only for those 

functions that have a return-area parameter. You must include this element in every 

program that calls one of these PCFP functions before any element that defines a 

specific function packet that contains the return-information portion. 

• fp$fffffffff.h 

This name refers to each of the elements that contains the typedef definition of a 

specific function packet. Each of these elements also contains the function 

prototype definition and the work area requirements for the function. Exactly one of 

these elements exists for each PCFP function. fffffffff signifies an abbreviated 

mnemonic for the function with which the include element is associated. You must 

include one of these elements in your program for each different PCFP function that 

it calls. You need not include elements for any PCFP functions that your program 

does not call. 

• fp$rtn$rrrrr.h 

This name refers to the elements that contain the typedef definitions of the 

repeating structures that certain PCFP functions return. One of these include 

elements exists for each unique structure that PCFP can return. rrrrr is an 

abbreviated mnemonic for the structure defined by the element. You need include 

only those elements of this set that are used by the PCFP functions that your 

program calls. The function descriptions in Sections 3 – 10 state which return 

structures are used with each PCFP function. 

The following example illustrates the #include statements required before your program 

calls the acq_elt_info function. Note that this function has a return-area parameter, and 

therefore requires inclusion of elements to define the return-information portion of the 

function packet, and the return_elt_info structure. 

#include 

#include 

#include /*optional*/ 

#include 

#include 

#include 

#include 

11.2. Naming Conventions 

For C programs, the names of all functions, structures, items, and constants used by 

PCFP are lowercase. The exceptions are the global constants TRUE, FALSE, and NULL, 

which are all uppercase. All globally defined names begin with the characters fp_ or 

_fp_. Avoid defining names starting with these characters in programs that call PCFP, so 

that there are no conflicts between the names you define, and the names defined for 

PCFP. 

11–2 7830 9796–013

11.2.1. Function Names 


For C programs, the names of all PCFP functions are identical to the function names 

given in Sections 3 – 10, except that the C names are in lowercase, and are prefixed with 

the characters _fp_. 

11.2.2. Typedef Names 

For C programs, the names of all PCFP typedef structures start with the characters fp_, 

and end with the characters _type. The names of all PCFP typedef enumeration lists 

start with fp_, and end with _list. 

11.2.3. Item Names 

For C programs, the names of all items within structures are exactly the same as shown 

in Sections 2 – 10, except that all letters in the names are lowercase. Item names do 

not have the fp_ prefix, since each item name can be qualified by the structure that 

contains it, and hence does not need to be globally unique. 

11.2.4. Names of Constants 

For C programs, the names of all PCFP constants start with the prefix fp_. In addition, 

for those constants that are part of a list of constants, the characters fp_ are followed by 

a short abbreviation that identifies the list to which the constant belongs. This naming 

scheme assures the global uniqueness of all constant names. 

Constant names that are used by multiple PCFP functions are defined in include element 

fp$defs.h (except error and warning codes, which are defined in fp$errors.h). Constant 

names that are associated only with a single structure usually are defined in the include 

element that defines that structure. 

The following prefixes are used for those constants that are part of a list of constants: 

fp_err_ 

PCFP error codes 

fp_warn_ 

PCFP warning codes 

fp_cycle_ 

File and element cycle types 

fp_elt_type_ 

Element types 

7830 9796–013 11–3


fp_st_ 

fp_ast_ 

Subtypes for symbolic and omnibus elements 

Subtypes for absolute elements 

fp_detail_ 

Levels of information detail that can be returned by a function 

fp_on_conflict_ 

Actions that can be taken by PCFP if an element name-version-type conflict occurs 

fp_text_ 

Element text types 

fp_equip_ 

fp_lff_ 

File equipment types 

Logical file format types 

fp_on_end_ 

Actions that can be taken upon reaching the end of a tape file 

fp_min_work_area_ 

Minimum sizes of the work area required by specific functions 

fp_max_work_area_ 

Maximum sizes of the work area usable by specific functions 

11.3. PCFP Data Types 

This subsection describes the C constructs used to define the various data types used 

by PCFP. 

11–4 7830 9796–013

11.3.1. Structure Declarations 


The declarations of all structures used by PCFP are in the form of typedef declarations. 

Each of these declarations creates a data type that gives the form of the structure, but 

does not define the actual structure. The programs that call PCFP must define the actual 

structures, using the typedef data types declared in the PCFP include elements. 

The following special considerations apply to structures that are returned in the return 

area: 

• A structure of this type should typically be defined as an array, or as the object of a 

pointer that is set to the start of a general return area. 

• For many of the return structures, both a short form and a long form exist. Both 

forms are declared in the same include element. The form returned by a PCFP 

function depends upon what the calling program has specified in the function packet. 

• In a few cases, a return structure ends with an array of indeterminate size. Some of 

the substructures returned by the _fp_acq_file_info function, defined in fp$rtn$file.h, 

are in this category. The C language requires that the typedef declaration of such a 

structure be given an exact array bound (instead of an unspecified bound). In the 

PCFP include elements, such arrays are declared with an arbitrary size of 10 to 

satisfy this requirement. However, the actual size of the array returned by PCFP can 

be smaller or larger. 

11.3.2. Implementing Generic Data Types 

In 2.2, a number of generic data types are described. The following list explains how 

these data types are implemented for PCFP in the C language: 

• The character generic data type is implemented in C as an array of type char. The 

size of the array is equal to the defined length of the string. 

When you move a string value shorter than the defined length of the target string, 

indicate the actual end of the string with a null character. 

A string returned by PCFP can be terminated either with null characters or with 

space characters, if it is shorter than the declared size of the string. The usual 

C-language convention is to terminate with null characters. To cause this, your 

program must set the item gen.null_term_strings to TRUE in the function packet 

before calling PCFP. 

Note: A string is not null-terminated if its length is equal to the declared size of the 

string. 

• The integer generic data type is implemented in C as an item of basic type int. 

Integer items are further designated as signed or unsigned, depending on the values 

they can assume. The size of integer items is indicated by the designators short or 

long, or by an actual bit size. 

7830 9796–013 11–5


• The condition generic data type is implemented in C as the user-defined data type 

fp_condition, which in turn is defined as a 1-bit unsigned integer. Your program 

should set condition items only to the defined values of FALSE (0) and TRUE (1). 

• Each value-list generic data type is implemented in C by means of a user-defined 

typedef. The typedef declaration is defined in one of two ways: 

− In cases where all the items declared with the data type occupy 18 bits, the 

typedef is defined as an enumeration type. The enum definition specifies the 

constant values that the items can be assigned. 

− In other cases, the typedef is defined as an unsigned integer type. Following the 

typedef definition, a series of #define statements specifies the constant values 

that the items can be assigned. 

• The date-time generic data type is implemented in C by means of the following 

typedef structure: 

typedef struct 

{ unsigned int year : 18; 

unsigned int month : 9; 

unsigned int day : 9; 

unsigned int milliseconds : 36; 

} 

fp_date_time_type; 

• Some PCFP structures contain items called bit arrays. Logically, these items can be 

considered one-dimensional arrays, each item of which has the data type of 

condition, and occupies exactly one bit position. This type of structure cannot be 

represented directly in C. Instead, a bit-array item is defined as an unsigned integer. 

If the bit array cannot fit into a single word (36 bits), it is defined as an array of 

unsigned integers. See 11.4.7 for details on how to set the bit items within a bit 

array. 

11.4. Operating Rules and Coding Sequences 

This subsection describes specific rules and coding sequences that must be used in C 

programs that call PCFP. 

11.4.1. Parameter Definitions 

The calling program must define all parameters that it passes to the PCFP functions it 

calls, using the typedef data types declared in the PCFP include elements. The 

definitions are necessary, since the include elements only declare the forms of the 

parameters used by PCFP, not the parameters themselves. 

A PCFP parameter can be defined directly, or it can be declared as the object of a 

pointer. A parameter can have a storage class of auto, static, or extern. If a parameter 

is declared as the object of a pointer, it also could be allocated dynamically. 

11–6 7830 9796–013


The following example shows declarations that might be used for the _fp_acq_elt_info 

function. The function packet structure is defined in auto storage (the default inside of 

functions). The file identifier structure is defined as the object of pointer p_file_id, 

perhaps because it will be allocated dynamically. The elt_info array is declared extern, 

perhaps because another C routine has allocated the space for this array, and will 

process the data placed by PCFP into it. This array is declared large enough to contain 

100 occurrences of the long form of the element entry. 

fp_acq_elt_info_type acq_elt_pkt; 

fp_file_id_type *p_file_id; 

extern fp_rtn_elt_info_long_type elt_info [100]; 

11.4.2. Initializing Input Parameters 

Before your program assigns values to specific items of an input parameter, it should 

zero-fill the entire parameter. This insures that all defined items in the structure are 

initialized to their default values, and that all unassigned areas in the structure contain 

zero (as required by PCFP). For most functions, the input parameters that you must 

initialize with zero are the function packet and the file identifier(s). It is not necessary to 

zero-fill a return area parameter. 

You can use the memset function to zero-fill PCFP parameter structures. The following 

example shows how to use this function to zero-fill the fp_acq_elt_info_type function 

packet defined earlier. 

memset ( &acq_elt_pkt, 0, sizeof(fp_acq_elt_info_type) ); 

Alternatively, if your program declares a PCFP parameter as the object of a pointer, and 

allocates it dynamically, you can use the calloc function to zero-fill the parameter at the 

time it is allocated. The following example shows allocation and zeroing of a file 

identifier structure using the pointer defined earlier. 

p_file_id = (fp_file_id_type *) 

calloc ( 1, sizeof(fp_file_id_type) ); 

11.4.3. Assigning Values to Character Strings Within Structures 

To assign a character string to a character item, use the strncpy function. Precede the 

item name with the structure name and a period. For example, to assign the string 

ABCDEFG to item elt_name in the structure acq_elt_pkt, use the following statement: 

strncpy (acq_elt_pkt.elt_name, 

"ABCDEFG", 

sizeof (acq_elt_pkt.elt_name)); 

Note that this statement causes the value in elt_name to be null-terminated if it is 

shorter than the size of elt_name. Also, the value placed into elt_name cannot overflow 

into the next item if the value is larger than the size of elt_name. 

7830 9796–013 11–7


11.4.4. Work Area Parameter 

The last parameter of every PCFP function is the work area parameter. In the current 

release of PCFP, the work area is always allocated internally by PCFP, so this parameter 

is unused. Always code this parameter as NULL. 

Although PCFP always allocates its own work area, the calling program must indicate 

how large to make it. The include element for each function defines constants giving the 

minimum and maximum work area sizes for that function. The description of each 

function in Sections 3 – 10 indicates in general terms the work area needs of that 

function. Before your program calls PCFP, you must set the item gen.work_area_size in 

the function packet, based on your projected needs for that function. 

11.4.5. Calling PCFP 

All PCFP functions are true functions, in that they return a value. This returned value is 

the ELMS error code generated by the function. (This error code is also returned in the 

item error_code in the generic part of the function packet.) 

You can code a PCFP function in a C program in any context that allows a function call. 

If your program is not coded to examine the function value returned by PCFP, it can 

examine the value of the item gen.error_code returned in the function packet instead. 

You must code each parameter to each PCFP function as the address of the actual 

parameter structure. You can do this by using the & operator, or by specifying an array 

name or pointer variable without the & operator. 

The following example shows a call to the function acq_elt_info. This example uses the 

structures declared in 11.4.1. The first parameter includes the & operator, since the 

associated structure is not an array. The second parameter is a pointer variable 

containing the location of the parameter structure. The third parameter is an array name 

without a subscript. The last parameter is NULL, as explained in 11.4.4. 

err_code = _fp_acq_elt_info (&acq_elt_pkt, 

p_file_id, 

elt_info, 

NULL); 

11–8 7830 9796–013

11.4.6. Handling Error Conditions 


Your program can determine if any warning or error occurred by examining the item 

error_class in the function packet. If a warning or error has been returned by the 

function, the items error_file, sub_error_code, error_code, and aux_error_code provide 

further information you can use to handle the problem. Your program can handle errors 

and warnings in a number of ways: 

• Your program can print the error code. To do this, your program should take the 

remainder of the error code after dividing by 01000000, using the modulus operator: 

err_code % 01000000 

The number printed in this fashion corresponds to the message numbers listed in 

Appendix A. 

• Your program can check for specific error code values defined in element 

fp$errors.h. This is necessary if your program must take special action for certain 

error conditions. Use the entire error code value to make the comparison. 

• Your program can call ELMS to print a message appropriate for the error code. Use 

the entire error code value as the error_status supplied to ELMS. 

11.4.7. Items in a Bit Array 

As noted in 11.3.2, an item that is described as a bit array is defined in C as an unsigned 

integer, or an array of unsigned integers. To set items in such a bit array, you can use 

the left bitwise shift operator


11.4.8. Date-Time Items 

You can use the following techniques to handle PCFP date-time items within a C 

program. 

• To initialize a date-time value to a specific value, set each item within the date-time 

structure to the desired value. For example, to set item acq_elt_pkt.max_date_time 

to represent March 25, 1991, at 14:35:20, use the following assignment statements: 

acq_elt_pkt.max_date_time.year = 1991; 

acq_elt_pkt.max_date_time.month = 3; 

acq_elt_pkt.max_date_time.day = 25; 

acq_elt_pkt.max_date_time.milliseconds = 

(14*60*60*1000) + (35*60*1000) + (20*1000); 

• To copy a date-time value from one item to another, use a single assignment 

statement, as in the following example. (This example assumes that my_date_time 

is a variable declared with type fp_date_time_type.) 

acq_elt_pkt.max_date_time = my_date_time; 

• To compare the values in two date-time items, use the memcmp function. For 

example, to determine if the value from my_date_time is less than the value in 

acq_elt_pkt.max_date_time, use the following statement fragment: 

11.4.9. Return Area 

if ( memcmp (&my_date_time, 

&acq_elt_pkt.max_date_time, 

sizeof (fp_date_time_type)) < 0 ) 

The following subsections describe information you must consider when you specify a 

return area for those PCFP functions that can return a variable amount of information to 


11.4.9.1. General Considerations 

For your program to receive return entries from a PCFP function that can return such 

entries, your program must indicate the following: 

• The proper form (short or long) of the data structure that describes the entry 

• The form of return entries your program requires 

• The location and size of the return area into which PCFP returns these entries 

It is important that you keep this information compatible. Failure to keep this information 

compatible might cause either PCFP to attempt to return data into unassigned storage or 

your program to interpret incorrectly the data PCFP returns. 

To indicate the form of the return entry required, set the item info_detail in the function 

packet to the required value (fp_detail_short or fp_detail_long). 

11–10 7830 9796–013


To specify a return area for PCFP, you must code the address of the return area as the 

return area parameter to the function, and you must assign the size of the return area to 

the item rtn_info.rtn_area_size in the function packet. You must specify this size in 

words. 

If you do not want a function to return any data in the return area, simply code the return 

area parameter as NULL, and leave rtn_info.rtn_area_size at its initialized value of 0. 

You can declare a return area in a number of ways. If your program will receive only a 

single type of structure in the return area, you can simply declare an array composed of 

that structure type. You must choose the size of the array based upon the maximum 

amount of data that you expect PCFP to return, or the maximum amount that you want 

your program to process. The following example sets up and uses a return area in this 

fashion: 

/*Declare the array of element entries to be returned by PCFP.*/ 

fp_rtn_elt_info_long_type elt_info [100]; 

. 

. 

. 

/*Set the word size of return area in the function packet.*/ 

acq_elt_pkt.rtn_info.rtn_area_size = sizeof (elt_info) / 4; 

. 

. 

. 

/*Call the PCFP function to retrieve the element entries.*/ 

_fp_acq_elt_info (&acq_elt_pkt, 

&file_id, 

elt_info, 

NULL); 

. 

. 

. 

/*Process the entries of the elt_info array here.*/ 

for (i=0; i


The following example sets up and uses the same return area for information returned 

by both acq_elt_info and acq_om_ep_info: 

/*Declare the Return Area*/ 

long int rtn_area [2000]; 

/*Declare pointers that refer to the arrays of information 

returned by the acq_elt_info and acq_om_ep_info functions.*/ 

fp_rtn_elt_info_long_type *p_elt; 

fp_rtn_om_ep_info_long_type *p_om_ep; 

. 

. 

. 

/*Set word size of Return Area in function pkt for acq_elt_info.*/ 

acq_elt_pkt.rtn_info.rtn_area_size = sizeof (rtn_area) / 4; 

. 

. 

. 

/*Set elt_info pointer to the start of rtn_area.*/ 

p_elt = (fp_rtn_elt_info_long_type *) rtn_area; 

. 

. 

. 

/*Call the acq_elt_info function.*/ 

_fp_acq_elt_info (&acq_elt_pkt, 

&file_id, 

p_elt, 

NULL); 

. 

. 

. 

/*Process the element entries in the Return Area here.*/ 

for (i=0; 

i

*Call the acq_om_ep_info function.*/ 

_fp_acq_om_ep_info (&acq_om_ep_pkt, 

&file_id, 

p_om_ep, 

NULL); 

. 

. 

. 

/*Process the OM EP entries in the Return Area here.*/ 

for (i=0; 

ifull_entry_size ); 

7830 9796–013 11–13


Each file return entry has associated with it a number of substructures that contain the 

optional information describing the file. The base entry for the file contains a number of 

offset items; these indicate which of the optional substructures is present, and where 

they are located. If the offset value for a substructure is zero, that substructure is not 

present. If the offset value is nonzero, it gives the offset in words from the start of the 

base entry for the file. You can use a code sequence similar to the following to obtain a 

pointer to one of these substructures. (In the actual code, replace XXX by the name of 

the particular substructure you want.) 

fp_rtn_file_info_type *p_file_info; 

fp_rtn_file_info_XXX_type *p_XXX_info; 

. 

. 

. 

p_XXX_info = (fp_rtn_file_info_XXX_type *) 

( (int *) p_file_info + p_file_info->XXX_info_offset ); 

11.5. Compiling and Linking Programs That Use 

PCFP 

Compile a C program that calls PCFP exactly as you compile any other C program. No 

special statements or options are required. As stated earlier, include elements for PCFP 

are contained in file SYS$LIB$*PROC$, and are found automatically by the compiler. 

All linking required for a C program to call PCFP is handled transparently by the Linking 

System. This is true whether you use dynamic linking or static linking for your program. 

The file that contains the PCFP executable code is in the default link search chain, so 

that the Linking System can always resolve references from your program to PCFP 

without any special statements or options. 

11.6. Programming Examples 

This subsection contains examples of three C programs each calling a different PCFP 

function. These examples correspond to those in 1.3. 

11–14 7830 9796–013



This example shows a C program that calls the _fp_delete_file function to delete the file 

A*B. 

/* EXAMPLE1 */ 

/* Delete file A*B. */ 

#include 

#include 

#include 

#include 

#include 

#include 

#include 

main() 

{ 

/* Define the function packet */ 

fp_delete_file_type df_pkt; 

/* Define the file identifier structure. */ 

fp_file_id_type file_id; 

/* Zero-fill the function packet. */ 

memset (&df_pkt, 0, sizeof (fp_delete_file_type)); 

/* Set items in the function packet. */ 

df_pkt.gen.interface_level = fp_interface_level_1; 

df_pkt.gen.null_term_strings = TRUE; 

df_pkt.gen.work_area_size = fp_max_work_area_delete_file; 

/* Zero-fill the file identifier. */ 

memset (&file_id, 0, sizeof (fp_file_id_type)); 

/* Set items in the file id. */ 

file_id.interface_level = fp_interface_level_1; 

strncpy (file_id.qualifier, 

"A", 

sizeof (file_id.qualifier)); 

strncpy (file_id.filename, 

"B", 

sizeof (file_id.filename)); 

_fp_delete_file (&df_pkt, 

&file_id, 

NULL); 

if ( df_pkt.gen.error_class != fp_error_class_none ) 

printf ("File was not deleted - error code: % u\n", 

df_pkt.gen.error_code % 01000000); 

} 

7830 9796–013 11–15



This example shows a C program that calls the _fp_copy_raf_raf function to copy the 

contents of mass storage file A*B(2) to the mass storage file with internal name FILE2. 


/* Copy mass storage file A*B(2) into mass storage file FILE2. */ 

#include 

#include 

#include 

#include 

#include 

#include 

#include 

main() 

{ 


fp_copy_raf_raf_type cpy_pkt; 

/* Define the file identifier structures. */ 

fp_file_id_type source_file_id; 

fp_file_id_type dest_file_id; 


memset (&cpy_pkt, 0, sizeof (fp_copy_raf_raf_type)); 


cpy_pkt.gen.interface_level = fp_interface_level_1; 

cpy_pkt.gen.null_term_strings = TRUE; 

cpy_pkt.gen.work_area_size = fp_max_work_area_copy_raf_raf; 

/* Zero-fill the source file identifier. */ 

memset (&source_file_id, 0, sizeof (fp_file_id_type)); 

/* Set items in the source file id. */ 

source_file_id.interface_level = fp_interface_level_1; 

strncpy (source_file_id.qualifier, 

"A", 

sizeof (source_file_id.qualifier)); 

strncpy (source_file_id.filename, 

"B", 

sizeof (source_file_id.filename)); 

source_file_id.f_cycle_type = fp_cycle_abs; 

source_file_id.f_cycle = 2; 

/* Zero-fill the destination file identifier. */ 

memset (&dest_file_id, 0, sizeof (fp_file_id_type)); 

/* Set items in the destination file id. */ 

dest_file_id.interface_level = fp_interface_level_1; 

strncpy (dest_file_id.filename, 

"FILE2", 

sizeof (dest_file_id.filename)); 

11–16 7830 9796–013

_fp_copy_raf_raf (&cpy_pkt, 

&source_file_id, 

&dest_file_id, 

NULL); 

if ( cpy_pkt.gen.error_class != fp_error_class_none ) 

printf ("File was not copied - error code: % u\n", 

cpy_pkt.gen.error_code % 01000000); 

else 

printf ("Successful copy - tracks copied: % u\n", 

cpy_pkt.amount_copied/1792); 

} 



Program File 

This example shows a C program that calls the _fp_acq_elt_info function to acquire all 

information about the symbolic elements in program file A*B. This example prints the 

name, version, subtype, and sequence number of each element for which PCFP 

returned information. 


/* Print name, version, subtype, and sequence number 

for all symbolic elements in file A*B. */ 

#include 

#include 

#include 

#include 

#include 

#include 

#include 

#include 

#include 

main() 

{ 


fp_acq_elt_info_type acq_pkt; 

/* Define the file identifier structure. */ 

fp_file_id_type file_id; 

/* Define an array to contain the information returned. */ 

fp_rtn_elt_info_long_type elt_info [125]; 

int i; /* Array index */ 


memset (&acq_pkt, 0, sizeof (fp_acq_elt_info_type)); 

7830 9796–013 11–17



acq_pkt.gen.interface_level = fp_interface_level_1; 

acq_pkt.gen.null_term_strings = TRUE; 

acq_pkt.gen.work_area_size = fp_max_work_area_acq_elt_info; 

acq_pkt.rtn_info.rtn_area_size = sizeof (elt_info) / 4; 

acq_pkt.sym_type = TRUE; 

acq_pkt.info_detail = fp_detail_long; 

/* Zero-fill the file identifier. */ 

memset (&file_id, 0, sizeof (fp_file_id_type)); 

/* Set items in the file id. */ 

file_id.interface_level = fp_interface_level_1; 

strncpy (file_id.qualifier, 

"A", 

sizeof (file_id.qualifier)); 

strncpy (file_id.filename, 

"B", 

sizeof (file_id.filename)); 

_fp_acq_elt_info (&acq_pkt, 

&file_id, 

elt_info, 

NULL); 

if ( acq_pkt.gen.error_class != fp_error_class_none ) 

printf ("Acq_Elt_Info not successful - error code: % u\n", 

acq_pkt.gen.error_code > 01000000); 

else 

{ 

printf ("Number of elements selected: % u\n", 

acq_pkt.num_selected); 

}; 

} 

for ( i = 0; 

i < acq_pkt.rtn_info.num_entries_in_rtn_area; 

i++ ) 

{ 

printf ("%-12.12s / %-12.12s %.4s % u\n", 

elt_info[i].elt_name, 

elt_info[i].elt_version, 

elt_info[i].elt_subtype_name, 

elt_info[i].seq_num); 

}; 

11–18 7830 9796–013

Section 12 

Using PCFP with COBOL 

This section contains information about using PCFP with programs written in COBOL. 

12.1. Copy Considerations 

All PCFP copy elements used by COBOL programs have a version name of COB, and all 

have names beginning with the characters FP$. The PDP processor makes COBOL 

procedures from these copy elements. These COBOL procedures are all contained in 

the file SYS$LIB$*PROC$, which is searched automatically by the UCOB compiler. 

Thus, it is not necessary to code the file name in the COPY statement. The 

recommended form for including COBOL PCFP definition procedures is 

COPY FP-xxxxxxxxx. 

where xxxxxxxxx represents the specific part of the procedure name. 

Include the following PCFP COBOL procedures in most or all COBOL programs that call 

PCFP: 

• FP-DEFS. 

This COBOL procedure contains the definition of constants that are used by all PCFP 

subroutines. You must copy this COBOL procedure in every program that calls 

PCFP, and you must include it before any other PCFP procedures in the 

WORKING-STORAGE SECTION as follows: 

WORKING-STORAGE SECTION. 

COPY FP-Defs. 

• FP-ERRORS. 

This COBOL procedure contains constant definitions of error codes that PCFP can 

return. You must copy this procedure only if your program refers to specific error 

codes by their defined names. 

COPY FP-Errors. 

7830 9796–013 12–1


• FP-FILE-ID. 

This COBOL procedure contains the definition of the file identifier record, which is 

used as a parameter by most PCFP subroutines. You must copy this COBOL 

procedure into any program that calls PCFP subroutines that require a source file 

identifier parameter. 

COPY FP-File-Id. 

If the PCFP subroutine also requires a destination file identifier, you must copy this 

COBOL procedure a second time, using the REPLACING clause as follows: 

COPY FP-File-Id REPLACING FP-File-Id BY FP-Dest-File-Id. 

• FP-fffffffff. 

This name refers to each of the COBOL procedures that contains the definition of a 

specific subroutine packet. fffffffff is the subroutine name as given in Sections 3 – 

10. Exactly one of these COBOL procedures exists for each PCFP subroutine. Each 

of these COBOL procedures also contains the work area requirements for the 

subroutine. You must copy one of these COBOL procedures into your program for 

each different PCFP subroutine that it calls. Do not copy COBOL procedures for any 

PCFP subroutine not called by the program. 

To define the subroutine packet for the FP-Acq-Elt-Info subroutine, use the following 

statement: 

COPY FP-Acq-Elt-Info. 

• FP-RTN-rrrrr. 

This name refers to the COBOL procedures that contain the definitions of the 

repeating records that certain PCFP subroutines return. One of these procedures 

exists for each unique record that PCFP can return. rrrrr is a mnemonic for the 

record defined by the procedure. Include in your program only those procedures 

used by the PCFP subroutines that your program calls. The subroutine descriptions 

in Sections 3 – 10 state what return records are returned by each PCFP subroutine. 

Set the maximum number of return records expected by replacing a variable in the 

return procedure with the number of records desired. To set the maximum number 

of return records, use the following clause: 

REPLACING xxxx-Array-Size BY yyy 

where xxxx is the name of the array and yyy is the maximum number of return 

records expected. 

For many of the return records, both a short and a long form exist. Each form is 

defined in a separate procedure. The form returned by a PCFP subroutine depends 

upon what your calling program has specified as Info-Detail in the subroutine packet. 

To define an array of 100 short return records for the FP-Acq-Elt-Info subroutine, use 

the following statement: 

COPY FP-Rtn-Elt-Info-Short REPLACING Elt-Array-Size BY 100. 

12–2 7830 9796–013

• CALL-FP-fffffffff 


This name refers to each of the COBOL procedures that contains a CALL to a 

specific PCFP subroutine. fffffffff is the function name as given in Sections 3 – 10. 

At least one of these CALL procedures exists for each PCFP subroutine. If a PCFP 

subroutine returns records, at least two of these COBOL CALL procedures exist: 

one requesting the long form and one the short form of the return records. 

To CALL the PCFP subroutine FP-Acq-Elt-Info to obtain the short form of the return 

record, use the following statement: 

COPY Call-FP-Acq-Elt-Info-Short. 

This CALL procedure generates the following COBOL statement: 

CALL 'fp_acq_elt_info' USING FP-ACQ-ELT-INFO, 

FP-FILE-ID, 

FP-RTN-ELT-INFO-SHORT. 

You can also code the subroutine CALL directly. These CALL procedures are 

provided only for convenience. 

Note: These CALL procedures are copied into the PROCEDURE DIVISION of your 

program, unlike the other procedures that are copied into the DATA DIVISION. 


For COBOL programs, all globally defined names begin with the characters FP-. In 

programs that call PCFP, avoid defining names starting with these characters so that 

there is no conflict between the names you define and the names defined for PCFP. As 

with all names in COBOL, there is no distinction between uppercase and lowercase 

letters. 

12.2.1. Subroutine Names 

For COBOL programs, the names of all PCFP subroutines are identical to the function 

names given in Sections 3 – 10, except that the COBOL names use a hyphen ( - ) instead 

of an underscore ( _ ), and are prefixed with the letters FP-. 

The COBOL procedures supplied with PCFP and the examples in this section follow the 

convention that subroutine names appear in all lowercase letters. 

12.2.2. Item Names 

For COBOL programs, the names of all items within records are exactly the same as 

shown in Sections 2 – 10, except that all COBOL names use a hyphen ( - ) instead of an 

underscore ( _ ). Item names do not have the FP- prefix, because each item name can 

be qualified by the record that contains it. Hence, item names do not need to be globally 

unique. 

7830 9796–013 12–3



convention that item names and the parts within them (alphabetic pieces separated by a 

hyphen) begin with an initial capital letter. Acronyms frequently used in this document 

appear in all capital letters, for example, RAF, SAF, and FP. 

Exceptions to the above rules occur when names of items conflict with COBOL reserved 

words, as follows: 

• PF is a COBOL reserved word. In the descriptions of the following items, the 

COBOL name for standard program file (spf ) is used instead of the documented 

name PF: 

− INIT_PROGRAM_FILE (4.1.2) 

− PROGRAM_FILE_TYPE (6.1.2) 

− INIT_DEST_FILE (7.1.2, 7.3.2, and 7.5.2) 

• TAPE is a COBOL reserved word. In 3.1.4.1 for the EQUIP_TYPE item, the COBOL 

name “tape-storage” is used instead of the documented name TAPE. 


The names of constants are implemented in COBOL in two different ways. 

• Constant names that are used by multiple PCFP subroutines are defined in 

procedure FP-DEFS. All of these PCFP constants start with the prefix FP-. For those 

constants that are part of a list of constants, the characters FP- are followed by a 

short abbreviation that identifies the list to which the constant belongs. This naming 

scheme assures the global uniqueness of all constant names. 

The following prefixes are used for those constants that are part of a list of 

constants: 

fp-err- PCFP error codes 

fp-warn- PCFP warning codes 

fp-ept- Object module entry point types 

fp-elt-subtype- Subtypes for symbolic, omnibus, and absolute elements 

fp-min-work-area- Minimum size of the work area required by specific subroutines 

fp-max-work-area- Maximum size of the work area usable by specific subroutines 

• Constant names that are associated with only a single record usually are defined in 

the COBOL procedure that defines that record. These constants are implemented in 

COBOL with 88 statements. Each 88 statement value list is unique to the data item 

that contains it. Therefore, these constant names do not start with the prefix FP-. 


convention that constant names appear in all lowercase letters. 

12.3. PCFP Data Types 

This subsection describes the COBOL constructs used to define the various data types 

used by PCFP. 

12–4 7830 9796–013

12.3.1. Record Definitions 


The definitions of all parameters used to call PCFP are in the form of COBOL records. 

The programs that call PCFP subroutines must declare storage for the parameter records 

by copying the necessary COBOL procedures into the WORKING-STORAGE SECTION 

as shown in the COBOL examples in 12.6. 

Special consideration applies to records that are returned by the Acq-File-Info and 

Acq-File-List subroutines. A file can have any number of use names and volume-ids. For 

PCFP to return all of these for any file requires a return record of variable size. Because 

this is difficult to accomplish in COBOL, the structure PCFP uses to return file 

information in COBOL contains exactly three occurrences of these items. In those cases 

where a file has more than three use names, PCFP returns only three, but places the 

total number that actually exist in item NUM_USE_NAMES. Similarly, PCFP returns no 

more than three volume-ids for a file, but places the true count in item NUM_VOLS. 

12.3.2. Implementing Generic Data Types 

In 2.2, a number of generic data types are described. The following list explains how 

these data types are implemented for the COBOL language. 

• The character generic data type is implemented in COBOL as PIC X. 

02 Elt-Name PIC X(12) USAGE DISPLAY. 

• The integer generic data type is implemented in COBOL as PIC 1. Integer items are 

unsigned, unless they are designated signed with an S in the PIC. 

02 Num-Entries PIC 1(18) USAGE BINARY-1. 

• The condition generic data type is implemented in COBOL as PIC 1(1). Condition 

items can be assigned only the values of 1 (signifying TRUE) and 0 (signifying 

FALSE). 

02 Abs-Type PIC 1(1) USAGE BINARY-1. 

• Some records contain items called bit arrays. Logically, these items can be 

considered one-dimensional arrays, each item of which occupies exactly one bit 

position. 

02 Abs-Subtype PIC 1(1) USAGE BINARY-1 

OCCURS 18 TIMES. 

• The value-list generic data type is implemented in COBOL by 88 statements. 

02 Info-Detail PIC 1(18) USAGE BINARY-1. 

88 short VALUE 0. 

88 long VALUE 1. 

• The date-time generic data type is implemented in COBOL by the following COBOL 

structure: 

02 Date-Time. 

03 Year PIC 1(18) USAGE BINARY-1. 

7830 9796–013 12–5


03 Month PIC 1(9) USAGE BINARY-1. 

03 Day-of-Month PIC 1(9) USAGE BINARY-1. 

03 Milliseconds PIC 1(36) USAGE BINARY-1. 


This subsection describes specific rules and coding sequences that must be used in 

COBOL programs that call PCFP subroutines. 


Before a program assigns values to specific items of an input parameter record, it must 

zero-fill the entire record. This ensures that all defined items in the record are initialized 

to their default values, and that all filler areas in the record contain zero (as required by 

PCFP). For most subroutines, the input parameters that the calling program must 

initialize with zero are the subroutine packet and the file identifier record(s). It is not 

necessary to zero-fill a return area record. 

Use the statement MOVE LOW-VALUES to zero-fill PCFP parameter records. Each 

PCFP subroutine COPY procedure provides guidance for zero-filling the record. 

The following example shows how to use the MOVE statement to zero-fill the 

FP-Acq-Elt-Info subroutine packet: 

MOVE LOW-VALUES TO FP-Acq-Elt-Info. 

12.4.2. Work Area Specification 

The work area is always allocated internally by PCFP, so this parameter is not used; 

therefore, do not code this parameter in the COBOL program. 

Although PCFP always allocates its own work area, the calling program must indicate 

how large to make it. The COPY procedure for each subroutine defines constants giving 

the minimum and maximum work area sizes for that subroutine. The description of each 

subroutine in Sections 3 – 10 indicates in general the work area needs of that subroutine. 

Before your program calls PCFP, it must set the item Work-Area-Size in the subroutine 

packet, based on your projected needs for that subroutine. 

12–6 7830 9796–013

12.4.3. Setting Items in a Bit Array 


As noted in 12.3.2, an item that is described as a bit array is defined in COBOL as an 

array of PIC 1(1) USAGE BINARY-1 items. 

To see an example of a bit array that uses the item Abs-Subtype-Array in the 

FP-Acq-Elt-Info subroutine packet, execute the example in 12.6.3. You may use a 

constant in the Abs-Subtype-List as an index to set a required bit in the Abs-Subtype bit 

array. However, you must add one (1) to these constants to use them as indexes. As an 

example, the following statement sets the appropriate bit of Abs-Subtype to acquire 

information only on object module (OM) absolute subtypes: 

MOVE 1 TO Abs-Subtype ( fp-elt-subtype-om + 1 ). 

You can use statements of this nature successively to set any number of bits within the 

same bit array. 

Note that Abs-Subtype only affects the selection of absolute elements. Also, if your 

program sets no items in this array, PCFP selects absolute elements regardless of 

subtype. 

12.4.4. Handling Date-Time Items 

The following techniques can be used to handle PCFP date-time items within a COBOL 

program. 

• To initialize a date-time item to a specific value, set each item within the date-time 

group item to the desired value. For example, to set item Max-Date-Time of 

FP-Acq-Elt-Info to represent March 25, 1991, at 14:35:20, use the following 

assignment statements: 

MOVE 1991 TO Year OF Max-Date-Time. 

MOVE 3 TO Month OF Max-Date-Time. 

MOVE 25 TO Day-of-Month OF Max-Date-Time. 

COMPUTE Milliseconds OF Max-Date-Time = 

(14 * 60 * 60 * 1000) + 

(35 * 60 * 1000) + 

(20 * 1000). 

• To compare the values in two date-time items, compare the date-time items as 

group items. For example, to determine if the value from Your-Date-Time is less 

than the value in Max-Date-Time, use the following statement: 

IF Your-Date-Time < Max-Date-Time 

7830 9796–013 12–7



The status generated by the call to a PCFP subroutine is returned in the subroutine 

packet. If the Error-Class equals none, the subroutine call was successful. If Error-Class 

does not equal none, a warning or error has occurred during the subroutine call and the 

items Error-Class, Error-File, Sub-Error-Code, Error-Code, and Aux-Error-Code provide 

information that can be used to determine the problem. 

Your program can print the Msg-Code portion of the error code. The number printed in 

this fashion corresponds to the message numbers listed in Appendix A. 

Your program can check for specific error code values defined in procedure FP-ERRORS. 

This is necessary if your program must take special action for certain error conditions. 

Use the entire error code value to make the comparison. 

12.4.6. Handling the Return Area Parameter 

The Return Area is used by those PCFP subroutines that can return a variable amount of 

information to the calling program. 

If you do not want a subroutine to return any data in the Return Area, leave the item 

Rtn-Area-Size in the subroutine packet at its initialized value (0). If you use the supplied 

CALL subroutine procedure, you must still include a copy of the return area record in the 

WORKING-STORAGE SECTION, because the CALL uses the standard return record as a 

parameter. If you are not using the supplied CALL subroutine procedure, you can code 

the Return-Area-Parameter with a zero as follows: 

CALL 'fp_copy_elt' USING FP-COPY-ELT, 

FP-FILE-ID, 

FP-DEST-FILE-ID, 

0. 

If you want a PCFP subroutine to return records in the return area, you must do the 

following: 

• Make sure the subroutine is designed to return records. The subroutine descriptions 

in Sections 3 – 10 state whether or not the subroutine returns any records. 

• COPY the correct return area procedure into your program, specifying the maximum 

expected number of return records as the array size. You must choose the size of 

the array (number of records) based upon the maximum number of records that you 

expect PCFP to return, or the maximum number you want your program to process. 

The following statement allows for 100 long element records to be returned by the 

FP-Acq-Elt-Info subroutine procedure. 

COPY FP-Rtn-Elt-Info-Long REPLACING Elt-Array-Size BY 100. 

12–8 7830 9796–013


• Specify the Rtn-Area-Size in the subroutine packet. You must specify this size in 

words. Each procedure that describes a return record contains a constant describing 

the length (in words) of that record, to aid in the calculation of the Rtn-Area-Size. As 

an example, to calculate the Rtn-Area-Size for 100 long return element records to be 

returned by the FP-Acq-Elt-Info subroutine, use the following statement: 

MULTIPLY 100 BY fp-rtn-elt-info-long-size GIVING Rtn-Area-Size. 

• Indicate in the subroutine packet the form of the return record you want: short or 

long. When your program initialized the subroutine packet, Info-Detail is set to its 

default value of short. To obtain the long form of the return record, set Info-Detail to 

long with the following statement: 

SET long OF Info-Detail TO TRUE. 

• COPY the appropriate PCFP CALL procedure that returns the matching form of the 

return record (short or long), so that the information returned can be used by the 

COBOL program. For example, use the following CALL procedure to call the 

FP-Acq-Elt-Info subroutine procedure to obtain the long form of element records in 

the return area: 

COPY Call-FP-Acq-Elt-Info-Long. 

Remember that you must keep the number of return records, Rtn-Area-Size, Info-Detail, 

and the CALL procedure compatible. If they are not compatible, either PCFP might 

attempt to return data into unassigned storage or your program might not correctly 

interpret the data PCFP does return. 


PCFP 

Compile a COBOL program that calls PCFP exactly as you compile any other COBOL 

program. No special statements or options are required. As stated earlier, COPY 

procedures for PCFP are contained in file SYS$LIB$*PROC$, and are found automatically 

by the compiler. 

All linking required for a COBOL program to call PCFP is handled transparently by the 

Linking System. This is true whether you use dynamic linking or static linking for your 

program. The file that contains the PCFP executable code is in the default link search 

chain, so that the Linking System can always resolve references from your program to 

PCFP without any special statements or options. 


This subsection contains examples of three COBOL programs, each calling a different 

PCFP function. These examples correspond to those in 1.3. 

7830 9796–013 12–9



This example shows a COBOL program that calls the FP-Delete-File subroutine to delete 

the file A*B. 

IDENTIFICATION DIVISION. 

PROGRAM-ID. example-1. 

ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 

SOURCE-COMPUTER. UNISYS-2200-11. 

OBJECT-COMPUTER. UNISYS-2200-11. 

SPECIAL-NAMES. PRINTER IS PRINTER. 

DATA DIVISION. 


* 

COPY FP-Defs. 

COPY FP-Delete-File. 


* 

PROCEDURE DIVISION. 

START-OF-PROGRAM. 

* Set up Delete File Subroutine Packet 

MOVE LOW-VALUES TO FP-Delete-File. 

MOVE fp-interface-level-1 TO Interface-Level 

OF FP-Delete-File. 

MOVE fp-max-work-area-delete-file TO Work-Area-Size 

OF FP-Delete-File. 

* Set up Source File Identifier 

* 

MOVE LOW-VALUES TO FP-File-Id. 


OF FP-File-Id. 

MOVE 'A' TO Qualifier OF FP-File-Id. 

MOVE 'B' TO Filename OF FP-File-Id. 

* Call Delete File - PCFP Subroutine. 

COPY Call-FP-Delete-File. 

* Check if the results are negative. 

IF NOT none OF Error-Class 

DISPLAY 'File was not deleted - Error Code: ' 

Msg-Code OF Error-Code UPON PRINTER 

END-IF. 

12–10 7830 9796–013

END 

* 



This example shows a COBOL program that calls the FP_Copy_RAF_RAF subroutine to 

copy the contents of mass storage file A*B(2) to the mass storage file with an internal 

name of FILE2. 










* 

COPY FP-Defs. 

COPY FP-Copy-RAF-RAF. 


COPY FP-File-Id REPLACING FP-File-Id BY FP-Dest-File-Id. 

* 



* Set up FP-Copy-RAF-RAF Subroutine Packet 

MOVE LOW-VALUES TO FP-Copy-RAF-RAF. 


OF FP-Copy-RAF-RAF. 

MOVE fp-max-work-area-copy-raf-raf TO Work-Area-Size 

OF FP-Copy-RAF-RAF. 

* Set up Source File Identifier 

* 






SET abs OF FP-File-Id TO TRUE. 

MOVE 2 TO F-Cycle OF FP-File-Id. 

* Set up Destination File Identifier 

MOVE LOW-VALUES TO FP-Dest-File-Id. 

7830 9796–013 12–11


* 


OF FP-Dest-File-Id. 

MOVE 'FILE2' TO Filename OF FP-Dest-File-Id. 

12–12 7830 9796–013

END 

* Call Copy-RAF-RAF - PCFP Subroutine. 

COPY Call-FP-Copy-RAF-RAF. 

* Check if the results are negative. 


DISPLAY 'File was not copied - Error-Code: ' 


ELSE 

* Print out amount copied in tracks. 

* 

DIVIDE Amount-Copied BY 1792 GIVING Amount-Copied 

DISPLAY 'Successful copy - Tracks-Copied: ' 

Amount-Copied UPON PRINTER 

END-IF. 


7830 9796–013 12–13



Program File 

This example shows a COBOL program that calls the FP_Acq_Elt_Info subroutine to 

acquire all information about the symbolic elements in program file A*B. This example 

prints the name, version, subtype, and sequence number of each element selected by 

PCFP. 










* 

COPY FP-Defs. 

COPY FP-Acq-Elt-Info. 


COPY FP-Rtn-Elt-Info-Long REPLACING Elt-Array-Size BY 100. 

01 SS PIC 9(10) USAGE BINARY. 

* 



* Set up Acq-Elt-Info Subroutine Packet. 

MOVE LOW-VALUES TO FP-Acq-Elt-Info. 


OF FP-Acq-Elt-Info. 

MOVE fp-max-work-area-acq-elt-info TO Work-Area-Size. 

MULTIPLY fp-rtn-elt-info-long-size BY 100 

GIVING Return-Area-Size. 

* Set up File Identifier Packet. 






* Set Symbolic Type only 

MOVE 1 TO Sym-Type OF FP-Acq-Elt-Info. 

12–14 7830 9796–013

END 


* Indicate that the long form of return information is desired. 

SET long OF FP-Acq-Elt-Info TO TRUE. 

* Call Acquire Element Information PCFP Function. 

COPY Call-FP-Acq-Elt-Info-Long. 

* Check for negative results. 


DISPLAY 'Acq-Elt-Info not successful - Error-Code: ' 


ELSE 

* Display number of elements selected by PCFP. 

DISPLAY 'Number of Elements Selected: ' 

Num-Selected UPON PRINTER 

* Print the Element Items returned by PCFP. 

* 

PERFORM VARYING SS FROM 1 BY 1 UNTIL SS > 

Num-Entries-in-Rtn-Area 

DISPLAY 

Elt-Name OF FP-Rtn-Elt-Info-Long (SS) '/' 

Elt-Version OF FP-Rtn-Elt-Info-Long (SS) ' ' 

Elt-Subtype-Name OF FP-Rtn-Elt-Info-Long (SS) ' ' 

Seq-Num (SS) UPON PRINTER 

END-PERFORM 

END-IF. 

7830 9796–013 12–15


12–16 7830 9796–013

Section 13 

Using PCFP with FORTRAN 

This section contains information about using PCFP with programs written in FORTRAN. 

Throughout this section, the term procedure is used to mean an INCLUDE procedure. 

13.1. INCLUDE Element/Procedure Considerations 

A number of FORTRAN procedures exist to assist a FORTRAN programmer in calling 

PCFP. Two of these procedures define constants and the remaining procedures define 

the function packets, file identifier packets, and repeating return information. These 

procedure names begin with the character sequence fp$. They exist in the file 

SYS$LIB$*PROC$, which is searched automatically by the UFTN compiler. These 

procedures exist in elements that, in most cases, have the same names as the 

procedure names. Slight differences exist between the procedure and element names 

for those procedures that define repeating return information. All PCFP include 

elements used by FORTRAN programs have a version name of FTN. Each of these 

general procedures is described in the following list: 

• FP$DEFS 

This procedure contains the names and the associated values for constants used in 

assigning values to 

− Value-list integer items within the packets presented to PCFP 

− The entries returned by PCFP 

You must include this procedure in every FORTRAN program that calls PCFP. When 

analyzing or inserting value-list items in any of the packets or in information returned 

by the PCFP, you are encouraged to use the symbolic names defined in this 

procedure. 

• FP$ERRORS 

This procedure defines the names and associated values of error codes returned by 

PCFP. You are encouraged to include this procedure within your program and to use 

the symbolic names defined in this procedure in any program that performs specific 

analysis of error codes returned by PCFP. 

• FP$SFILE$ID 

This procedure defines the source file identifier packet that is presented as an 

argument to most PCFP functions. Include this procedure in any program that calls a 

PCFP function that requires a source file identifier parameter. 

7830 9796–013 13–1


• FP$DFILE$ID 

This procedure defines the destination file identifier packet that is presented as an 

argument to those PCFP functions requiring both source and destination file 

identifier parameters. The destination file identifier packet has the same structure as 

the source file identifier packet; however, a different prefix is used to define the item 

names in this packet. Include this procedure in any program that calls a PCFP 

function that requires a destination file identifier parameter. 

• FP$GENERIC 

This procedure contains an illustration of the generic part of the function packet 

along with the prose describing the items within this portion of the function packet. 

This procedure contains documentation only and does not need to be included in any 

FORTRAN program with calls to PCFP. 

• FP$RTN$INFO 

This procedure contains an illustration of the return information portion of the 

function packet along with the prose describing the items within this portion of the 

function packet. This procedure contains documentation only and does not need to 

be included in any FORTRAN program with calls to PCFP. 

• FP$xxxxxx 

This generic procedure name represents the procedures that define the individual 

function packets. xxxxxx is between 6 and 9 characters in length and describes the 

function packet defined in the procedure. Each of these procedures defines all items 

in the following parts of the function packet: 

− Generic 

− Return information (if present) 

− Specific function 

Each of these procedures also contains 

− A description of the work area requirements for the function 

− Constants that define the minimum and maximum sizes of the work area 

− An illustration of the function packet 

− A description of each of the items within the function packet 

− An illustration of the form of the function call used to call the PCFP function and 

the arguments that must be presented on the call to the function 

13–2 7830 9796–013


Your FORTRAN program must include one of these procedures for each different PCFP 

function that it calls. 

• FP$RTN$yyyy 

This generic procedure name represents the procedures describing the repeating 

information entries returned by PCFP functions. There is a procedure for each 

unique entry, and, in cases where both a long and a short form of the entry can be 

returned, a procedure exists for each case. The names of the procedures for the 

long and short forms of the return entries are identical, except for the last character 

of the name. The last character is either the letter s, which designates the short 

form of the entry, or the letter l, which designates the long form of the entry. Your 

FORTRAN program must include the appropriate procedure for each PCFP function 

that returns repeating information. 

The following procedures must be included in a FORTRAN program that calls the 

FP_ACQ_ELT_INFO function of PCFP. 

INCLUDE FP$DEFS 

INCLUDE FP$ERRORS 

INCLUDE FP$SFILE$ID 

INCLUDE FP$ACQELTINF 

INCLUDE FP$RTN$ELTL 

Note that the last INCLUDE statement brings in the long form of the procedure that 

defines the repeating information returned by this function. 


For FORTRAN, the names of all constants, packets, and items within the packets begin 

with the characters FP_. If you avoid defining names beginning with these characters in 

your programs that call PCFP, you will have no conflicts between the names that you 

define and the names defined for PCFP. As with all names in FORTRAN, there is no 

distinction between uppercase and lowercase letters. 

13.2.1. Function Names 

The function names used in FORTRAN programs are identical to the function names 

given in Sections 3 – 10, except that the FORTRAN function names are all prefixed with 

the character sequence FP_. The FORTRAN procedures supplied with PCFP and the 

examples in this section follow the convention that function names appear in all 

uppercase letters. 

7830 9796–013 13–3


13.2.2. Packet Names 

For FORTRAN programs, the names of all function packets, file identifier packets, and 

repeating return entries begin with the characters fp_. Following these characters is a 2 

or 3 character mnemonic that represents the type of packet being defined. An example 

of this is the name of the function packet for the Delete_Elt function, which is fp_de. 

The packet names for those repeating entry types that have both a long and a short form 

contain either the letter l (long entry form) or the letter s (short entry form) as their last 

character. For example, the names for the long and short forms of the returned file 

entries are fp_rfl and fp_rfs respectively. The FORTRAN procedures supplied with PCFP 

and the examples in this section follow the convention that packet names appear in all 

lowercase letters. 

13.2.3. Item Names Within Packets 

For FORTRAN programs, the names of items within the packets are prefixed with the 

packet name. In most cases, the remainder of the item name is the same as it appears 

in the section that describes and illustrates the function. (In some cases, the item name 

has been shortened from that described in Sections 2 – 10 to allow the total name to fit 

within the 31 character limit imposed on symbolic names by FORTRAN.) For example, 

the name for the item min_f_cycle_type found in the function packet for the 

ACQ_FILE_LIST function, fp_afl , is fp_afl_min_f_cycle_type. The FORTRAN procedures 

supplied with PCFP and the examples in this section follow the convention that item 

names appear in all lowercase letters. 


The names of all PCFP constants are defined in either the procedure FP$DEFS or the 

procedure FP$ERRORS. All constant names begin with the characters fp_. Following 

this character sequence is a sequence of characters that define the class of the 

constant. This sequence, in turn, is followed by the symbolic name that is found in the 

description for value-list type of items. For example, in the procedure that defines the 

function packet for the ACQ_OM_EP_INFO function, FP$ACQOMEP, the description for 

TEXT_TYPE states that the item is an integer value-list that can take on the values 

NO_CONSTRAINT, ASCII, and KANJI. These names are generic names common to all 

of the programming languages. LIST 7 in the procedure FP$DEFS contains the 

FORTRAN names for these constants: fp_text_no_constraint, fp_text_ascii, and 

fp_text_kanji respectively. The FORTRAN procedures supplied with PCFP and the 

examples in this section follow the convention that constant names appear in all 

lowercase letters. 

13.3. Form of Packet Definitions 

All function packets and the file identifier packets are defined as one-dimension integer 

type arrays. The length of these arrays is simply the length in words of the packet being 

defined. Repeating return entries are defined as two-dimension integer arrays: 

• The length of the first dimension is the length in words of the entry. 

• The length of the second dimension is the expected number of returned entries. 

13–4 7830 9796–013


Both subscripts in the array definition for a repeating return entry are constants with 

names identical to the array name, except for the first character that follows fp_. For 

example: 

fp_rfl 

is the name of the long form of the returned file info entry. 

fp_lfl 

is the word length of this entry. 

fp_nfl 

is the expected number of these entries to be returned. 

The first subscript in the array definition for a repeating return entry is declared and 

assigned a value within the procedure containing the array definition. Prior to the 

INCLUDE statement containing the array definition, your program must define a constant 

representing the second subscript in the array definition. This constant defines the 

maximum number of entries you expect PCFP to return. 

A set of character arrays defined in the FORTRAN procedures permit character items to 

be defined within the packets and return entries. A character array, made equivalent 

(EQUIVALENCE) to the integer array, exists for each integer array that defines a function 

packet, file identifier packet, or repeating entry. For example: 

INTEGER fp_chs (17) 

is the integer array definition for the CHG_FILE_SEC function packet. 

CHARACTER*68 fp_chs_chr 

is the matching character array for the packet. 

EQUIVALENCE (fp_chs, fp_chs_chr) 

is the EQUIVALENCE of the two packets. 

Items of only two data types are defined within the PCFP structures. They are character 

type and integer type. The integer items are positioned within the integer arrays by 

means of the BITS function. The character items are positioned within the character 

arrays by means of the SUBSTR function. 

7830 9796–013 13–5



This subsection describes the specific rules and coding sequence that you must use in 

FORTRAN programs that call PCFP. 

13.4.1. Specifying Items Within Packets 

All items within the packets are defined as statement functions and your program must 

refer to them as such. Use no argument when you reference those statement functions 

that define items within a single dimension array. For example, the following statement 

function reference refers to the project-id item in the CHG_FILE function packet: 

fp_chf_project_id() 

You must use one argument (that is, the entry number) when referencing any item 

within a repeating return entry. For example, the following statement function reference 

refers to the element subtype name in the ith element name entry returned by the 

ACQ_ELT_INFO function: 

fp_rll_elt_s_typ_name(i) 

13.4.2. Handling Repeating Return Information 

In setting up a call to a PCFP function that returns repeating entries, your program must 

declare the symbolic name of an integer constant that defines the maximum number of 

entries that you expect the function to return. This item is the second subscript in the 

statement that defines the array of return entries. For example, assume that your 

program calls the PCFP function ACQ_ELT_INFO. Prior to calling this function, your 

program must include the procedure that defines the returned element information 

entries. Thus, your program must contain the statement: 


Note that this procedure defines the long form of the entry to be returned. This 

procedure contains the following array statement: 

INTEGER fp_rll(fp_lll,fp_nll) 

where the first subscript is the name of the constant that defines the length of each 

return entry and the second subscript is the name of the constant that defines the 

number of expected return entries. Your program must define the constant representing 

the second subscript prior to its inclusion of this procedure. Assume that you expect a 

maximum of 300 return element information entries. The sequence in your program to 

accomplish this appears as follows: 

INTEGER fp_nll 

PARAMETER ( fp_nll = 300) 


Your program must also assign the return area size to the item fp_xx_rtn_area_size in the 

function packet, where xx represents the function mnemonic. Using the above example, 

13–6 7830 9796–013


set the rtn_area_size as follows before calling the function to acquire element 

information: 

fp_ae_rtn_area_size() = fp_lll*fp_nll 

Finally, your program must indicate in the function packet the form of the return entries 

your program requires: short or long. When your program initializes the function packet, 

info_detail is set to its default value of short. To obtain the long form, as required by the 

example in this section, set info_detail to long with the following statement: 

fp_ae_info_detail() = fp_detail_long 

It is important that you make the form of the included return entries, the size of the 

return entry array, rtn_area_size, and info_detail compatible. If they are not compatible, 

either PCFP might attempt to return data into unassigned storage, or your program might 

not correctly interpret the data PCFP does return. 

If you do not want a function to return any data in the return area, define the item 

representing the second subscript in the array with a value of 0, and leave the item 

fp_xx_rtn_area_size at its initialized value of 0. 

13.4.3. Specifying Work Area 

The current release of PCFP allocates the work area internally. It is not specified in the 

calls to PCFP. Although PCFP allocates its work area, the calling program must still 

specify its size and set this value in the function packet. To assist the programmer in 

specifying the work area size, each procedure that defines a PCFP function packet also 

contains a description of the work area requirements for the function along with 

INTEGER and PARAMETER statements defining the maximum and minimum values for 

this item. 


Your program must initialize all input packets by filling them with zeros before calling 

PCFP. A suggested method of doing this is to set the entire array that represents the 

function or file identifier packet to 0. Thus, your program might use the following 

statements to zero-fill all of the input packets before calling PCFP function 

COPY_RAF_RAF: 

fp_crr = 0 

fp_fd = 0 

fp_fs = 0 

7830 9796–013 13–7


13.4.5. Handling Date-Time Items 

Each date time item in both the input and returned parameters is two words in length 

and contains 1 half-word and 2 quarter-word date subitems and one 1-word time 

subitem. All of these subitems are declared as integers. A character overlay of the 

entire date-time item is also defined. This overlay allows you to perform quick 

comparisons on the complete date-time items. The following program part illustrates 

this capability. Prior to executing this part, the program called the function 

ACQ_ELT_INFO to return the long form of all the elements in a program file. The 

purpose of this program part, which is in a DO loop that looks at every returned entry, is 

to get the name, version, and sequence number of the most recently created element in 

the program file and save this information for a later display. This program part is 

illustrated as follows: 

IF (fp_rll_create_dateteim(I) .GT. last_create_datetime()) THEN 

last_create_datetime() = fp_rll_create_datetime(I) 

last_elt_name() = fp_rll_elt_name(I) 

last_elt_version() = fp_rll_elt_version(I) 

last_seq_num() = fp_rll_seq_num(I) 

END IF 

13.4.6. Calling PCFP 

All PCFP functions are true functions in that they return a value. This returned value is 

the ELMS error code generated by the function. Your program must declare the item 

that is assigned the returned value as type integer. This error code is also returned as an 

item in the function packet. The form of each function call and the number, type, and 

sequence of the arguments submitted on the call is illustrated at the very beginning of 

the procedure that describes the function packet for the function. The following 

example illustrates a call to the COPY_ELT function: 

err_code = COPY_ELT ( fp_ce, fp_fs, fp_fd, fp_rll ) 

Note that your program must declare err_code as a type integer. Your program must 

specify the following four arguments on this function call: 

• The function packet (fp_ce) 

• The source file identifier packet (fp_fs) 

• The destination file identifier packet (fp_fd) 

• A return area into which PCFP returns the long form of element information (fp_rll) 

The COPY_SAF_SAF and COPY_RAF_SAF functions contain a zero as one of the 

arguments in the list. The zero is simply a placeholder for an argument that drives a 

feature not yet implemented. The zero must be coded in the argument list in order to 

maintain the proper argument order. The call to these two PCFP functions is illustrated 

below: 

err_code = COPY_RAF_SAF ( fp_crs, fp_fs, fp_fd, 0, fp_rsi) 

err_code = COPY_SAF_SAF ( fp_css, fp_fs, fp_fd, 0, fp_rsi, fp_rd1) 

13–8 7830 9796–013



Your program can determine if any warning or error occurred by examining the item 

error_class in the function packet. If a warning or error was returned by the function, the 

items error_file, sub_error_code, error_code, and aux_error_code provide further 

information that you can use to handle the problem. Your program can handle errors and 

warnings in the following ways: 

• Your program can print the error_msg_num portion of the error code. The number 

printed in this fashion corresponds to the message numbers listed in Appendix A. 

• Your program can check for specific error code values defined in procedure 

FP$ERRORS. This is necessary if your program must take special action for certain 

error conditions. Use the entire error code value to make the comparison. 


PCFP 

Compile a FORTRAN program that calls PCFP exactly as you compile any other 

FORTRAN program. No special statements or options are required. As stated earlier, 

include procedures for PCFP are contained in file SYS$LIB$*PROC$, and are found 

automatically by the compiler. 

All linking required for a FORTRAN program to call PCFP is handled transparently by the 

Linking System. This is true whether you use dynamic linking or static linking in your 

program. The file that contains PCFP executable code is in the default link search chain, 

so that the Linking System can always resolve references from your program to PCFP 

without any special statements or options. 


This subsection contains examples of three FORTRAN programs, each calling a different 

PCFP function. These examples correspond to those in 1.3. In the following examples, 

all FORTRAN commands, operators, and data specifications follow the normal FORTRAN 

convention of being specified in all uppercase characters. All other entities must follow 

the capitalization conventions specified in 13.2. 

7830 9796–013 13–9



This example shows a small FORTRAN program that calls the FP_DELETE_FILE function 

to delete the file A*B. 

PROGRAM EXAMPLE1 

* 

* Declare a variable to receive the value from the call to DELETE_FILE 

* 

INTEGER err_code 

* 

* INCLUDE all declarations needed to setup and call the DELETE_FILE 

* function 

* 



INCLUDE FP$FILE$ID , LIST 

INCLUDE FP$DELFIL , LIST 

* 

* Zero fill the file identifier packet and insert the file name A*B into 

* the packet. 

* 

fp_fs = 0 

fp_fs_interface_level() = fp_interface_level_1 

fp_fs_qualifier() = 'A' 

fp_fs_filename() = 'B' 

* 

* Zero-fill the function packet and set parameters into the packet. 

* Note that we are specifying the maximum size for the work area. 

* 

fp_df = 0 

fp_df_interface_level() = fp_interface_level_1 

fp_df_work_area_size() = fp_max_work_area_delete_file 

* 

* Call DELETE_FILE function with function packet and file identifier packet 

* 

err_code = FP_DELETE_FILE (fp_df, fp_fs) 

* 

* Print any errors that were encountered during the delete operation 

* 

IF (fp_df_error_class() .NE. fp_error_class_none) THEN 

100 FORMAT (1X, A35, I6) 

PRINT 100, 'File Was Not Deleted - Error Code:', 

* fp_df_error_msg_num() 

END IF 

STOP 

END 

13–10 7830 9796–013



This example shows a FORTRAN program that calls the function FP_COPY_RAF_RAF to 

copy the mass storage file A*B(2) to another mass storage file with the internal name 

FILE2. 


* 

* Declare a variable to receive the value from the call to COPY_RAF_RAF 

* 


* 

* INCLUDE all declarations needed for COPY_RAF_RAF setup and call 

* 



INCLUDE FP$DFILE$ID , LIST 

INCLUDE FP$SFILE$ID , LIST 

INCLUDE FP$CPYRAFRAF , LIST 

* 

* Zero fill the source file identifier packet and set file name in packet. 

* 

fp_fs = 0 




fp_fs_f_cycle() = 2 

fp_fs_f_cycle_type() = fp_cycle_abs 

* 

* Zero fill the destination file identifier packet and set file name in 

* packet. 

* 

fp_fd = 0 

fp_fd_interface_level() = fp_interface_level_1 

fp_fd_filename() = 'FILE2' 

* 

* Zero fill the function packet and set parameters into packet. 

* Note that we are specifying the maximum size for the work area. 

* 

fp_crr = 0 

fp_crr_interface_level() = fp_interface_level_1 

fp_crr_work_area_size() = fp_max_work_area_copy_raf_raf 

fp_crr_storage_to_release() = fp_release_none 

* 

* Call COPY_RAF_RAF function with function packet and 2 file identifier 

* packets 

* 

err_code = FP_COPY_RAF_RAF (fp_crr, fp_fs, fp_fd) 

* 

7830 9796–013 13–11


* If an error occurred, print prefix and the error code. Otherwise 

* print 'Successful Copy' along with the number of tracks that 

* were copied. 

* 

IF (fp_crr_error_class() .NE. fp_error_class_none) THEN 

100 FORMAT (1X, A34, I6) 

PRINT 100, 'File Was Not Copied - Error_Code: ', 

* fp_crr_error_msg_num() 

ELSE 

101 FORMAT (1X, A33, I8) 

PRINT 101, 'Successful Copy - Tracks Copied:', 

* fp_crr_amount_copied()/1792 

END IF 

STOP 

END 


Program File 

This example shows a FORTRAN program that calls the FP_ACQ_ELT_INFO function to 

acquire all information about the symbolic elements in program file A*B. Upon return 

from the function, and upon successful completion of the operation, the program prints 

out the number of elements that were selected and the name, version, element 

subtype, and sequence number of all the selected elements. If any error is returned by 

the PCFP function, this program prints a message with the error code. 


* 

* Declare a variable to receive the value from the call to ACQ_ELT_INFO 

* 


* 

* The parameter constant fp_nll denotes the expected number of 

* elements that will be selected. 

* 

INTEGER fp_nll 

PARAMETER ( fp_nll = 100 ) 

* 

* INCLUDE all declarations needed for ACQ_ELT_INFO setup and call 

* 



INCLUDE FP$SFILE$ID 

INCLUDE FP$ACQELTINF , LIST 

INCLUDE FP$RTN$ELTL , LIST 

* 

* Zero fill the source file identifier packet and set file name 

* in packet 

13–12 7830 9796–013


* 

fp_fs = 0 




* 

* Zero fill the function packet and set parameters into packet. Note 

* that we are specifying the maximum size for the work area, and 

* that we want to look at just the symbolic elements. Note also 

* we are specifying the long form of info_detail and that the size 

* of the return area must match the 100 (fp_nll) long entries that 

* we are expecting. 

* 

fp_ae = 0 

fp_ae_interface_level() = fp_interface_level_1 

fp_ae_work_area_size() = fp_max_work_area_acq_elt_info 

fp_ae_sym_type() = .TRUE. 

fp_ae_info_detail() = fp_detail_long 

* 

* Set return area size as the product of the length of the return entry 

* (fp_lll) and the number of expected return entries (fp_nll). 

* 

fp_ae_rtn_area_size() = fp_lll*fp_nll 

* 

* Call ACQ_ELT_INFO function with three parameters 

* 

err_code = FP_ACQ_ELT_INFO (fp_ae, fp_fs, fp_rll) 

IF (fp_ae_error_class() .NE. fp_error_class_none) THEN 

* 

* Print header and any error code when error_class NE none 

* 

100 FORMAT (1X, A42, I6) 

PRINT 100, 'ACQ_ELT_INFO Not Successful - Error Code:', 

* fp_ae_error_msg_num() 

ELSE 

* 

* Print header and the number of selected elements 

* 

102 FORMAT (1X, A29, I9) 

PRINT 102, 'Number of Elements S selected:', fp_ae_num_selected() 

* 

* Define line format for element information to be displayed and 

* then display information for each element in the file. 

* 

104 FORMAT (1X, A26, A5, I9) 

DO 105 I = 1, fp_ae_num_rtn_entries() 

105 PRINT 104, fp_rll_elt_name(I) // '/' // fp_rll_elt_version(I), 

* fp_rll_elt_s_typ_name(I), fp_rll_seq_num(I) 

END IF 

7830 9796–013 13–13


STOP 

END 

13–14 7830 9796–013

Appendix A 

Error Messages 

Each PCFP error code has an explanatory message and a symbolic name associated with 

it. The explanatory message exists in the ELMS database and is displayed either in a 

print file or on the screen by ELMS when the calling program presents the associated 

error code to ELMS. 

In this appendix, each PCFP explanatory message is presented in numerical order 

according to the decimal value associated with the message. When displayed by ELMS, 

the decimal value is preceded by the PCFP component-id PRA. Inserts in a message 

represent variable information that is supplied by the program calling ELMS. The inserts 

are shown in italic. For all error codes returned in the function packet, the calling 

program must supply Aux_Error_Code as the first numeric insert and Error_File as the 

second numeric insert. For those warnings returned in Result_Indicator of the element 

return information (see 7.1.5 and 8.1.4), the calling program must supply the element 

name as the first string insert, and the element version as the second string insert. 

Refer to the ELMS Programming Reference Manual for details on supplying message 

inserts to ELMS. 

A Sub_Error_Code of nonzero indicates that a PCFP function called another PCFP 

function as part of its processing, and the called function (subfunction) encountered an 

error. In this case, Error_Code describes the PCFP function and the subfunction it was 

calling, and Sub_Error_Code and Aux_Error_Code describe the error that was 

encountered by the subfunction. Because two messages are available, special error 

message handling is required to process both error messages. The following two 

methods can be used to process the error messages: 

• Call ELMS to display the Error_Code in the normal manner. When the call is 

complete, concatenate the severity and component identifier from Error_Code (18 

bits) with the message number from Sub_Error_Code (18 bits) to create an ELMS 

condition identifier. Call ELMS a second time to display the subfunction error 

message. 

• Supply the value Sub_Error_Code as the third numeric insert and request an ELMS 

explanation level of 2. ELMS displays the message for Error_Code followed by a 

display of the decimal Sub_Error_Code, octal Aux_Error_Code, and decimal 

Error_File. 

In this appendix, all Error_Codes with which Sub_Error_Codes can be associated are 

specially noted. 

The symbolic name for the message appears after the heading Symbolic Name. These 

symbolic names are defined in copy/include element FP$ERRORS for each language 

7830 9796–013 A–1


from which PCFP can be called. Any additional comments or explanations are supplied 

after the symbolic name. 

The error codes are grouped under the following headings: 

• Warnings and Informational Messages 

indicates that the function completed the operation with anomalies that should be 

noted 

• Errors 

indicates that the function did not complete the operation and that you need to 

check the program 

Some error messages indicate a PCFP internal error. If you receive an error of this kind, 

your system administrator should send a UCF describing the problem to Unisys. Other 

error messages indicate a system error. If you receive one of these errors, contact your 

system administrator to interpret the problem. 

A.1. Warnings and Informational Messages 

0001 The element / was copied as requested, but some or all of 

the procedure entries associated with this element were not inserted in the 

destination file because the procedure table in the destination file is completely 

full. 

Symbolic Name: fp_info_proc_toc_full 

0002 The element / was copied as requested, but some or all of 

the procedure entries associated with this element were not processed in the 

destination file because an error was encountered during procedure table 

operations. 

Symbolic Name: fp_info_proc_tbl_err 

0005 No name change was attempted. Either Chg_Qualifier and Chg_Filename are 

both FALSE or New_Qualifier and New_Filename specify the current name of 

the file. 

Symbolic Name: fp_info_no_name_chg 

0011 The tape file has been positioned at its logical end. 

Symbolic Name: fp_warn_at_saf_end 

As a result of the MOVE_SAF function just executed, the SAF has been 

positioned at its logical end. 

0013 The tape file has been positioned at the start of a volume. 

Symbolic Name: fp_warn_at_vol_start 

As a result of the MOVE_SAF function just executed, the SAF has been 

positioned at the start of one of its volumes. The logical file at this position 

might be a fragment continued from a previous volume; PCFP cannot copy 

such a logical file fragment. 

A–2 7830 9796–013


0021 The performance advantage of buffered-write mode BUFTAP is negated 

because Omit_Log_End_Mark is FALSE. 

Symbolic Name: fp_warn_buftap_negated 

For unlabeled destination tapes when Omit_Log_End_Mark is FALSE, the 

COPY_RAF_SAF and COPY_SAF_SAF functions write two tape marks (WEF$) 

and move backward between them (MB$). This backward tape movement 

causes the tape subsystem to synchronize the tape (write the data from the 

tape unit buffer to the physical tape). This negates the performance 

advantages of BUFTAP, which requires constant forward tape motion and no 

implicit or explicit tape synchronization requests. 

0051 The file to be deleted was assigned by one or more other runs. The file has 

been marked for deletion, but the actual deletion is delayed until all other runs 

have freed the file. 

Symbolic Name: fp_warn_delete_delayed 

0052 The file to be changed is assigned by your run and/or by another run. The 

changes you requested to the read-only and write-only indicators for the file 

have been made, but will not take effect until all runs have freed the file. 

Symbolic Name: fp_warn_chg_delayed 

The Exec delays changing the read-only and write-only indicators for a file until 

no runs have the file assigned. This includes the run that requested the change 

to these indicators. Any other changes requested for the file have been made 

and take effect immediately. 

0053 PCFP could not complete the requested privacy change for files 

of the F-cycle set because the files were in a ‘to be cataloged’ state for another 

run. 

Symbolic Name: fp_warn_chg_incomplete 

For CHG_FILE_KEYS this warning is returned when changing the keys for a 

removable pack F-cycle set. For CHG_FILE_SEC this warning is returned when 

changing the MFD Main Item privacy bit for an F-cycle set and when changing 

the clearance level, file owner user-id or ACR for a removable pack F-cycle set. 

To perform these changes PCFP must assign each file in the F-cycle set. The 

is the number of members of the F-cycle set that are currently 

“to be cataloged” by a different run and cannot be assigned and changed. Note 

that PCFP does not attempt to assign and change F-cycle members that are 

marked as “to be deleted.” 

To assure that all files in the F-cycle set have the same values, the PCFP 

function should be repeated after the “to be cataloged” F-cycle members are 

freed by the other run. Setting the WAIT_ON_FACILITIES item in the generic 

part of the function packet to TRUE assures that all F-cycle members have 

been freed before proceeding. 

0054 Name change completed for cataloged tape file. If this is a labeled tape file that 

was previously written without the F file assignment option, the tape cannot be 

read when assigned with the new file name. 

Symbolic Name: fp_warn_tape_may_be_unreadable 

7830 9796–013 A–3


0071 The element / was not copied because the destination file 

contains an element with the same name, version, and type. 

Symbolic Name: fp_warn_elt_conflict 

0072 The element / was not copied because the destination file 

contains an element with the same name, version, and type, and a date and 

time of creation which is more recent. 

Symbolic Name: fp_warn_elt_not_newer 

0073 The symbolic element / was not copied because the 

specific cycle specified does not exist. 

Symbolic Name: fp_warn_nonexistent_sym_cycle 

0076 The element / could not be copied or changed because the 

new name generated for the element contains an embedded space. 

Symbolic Name: fp_warn_bad_elt_name 

0077 The element / could not be copied or changed because the 

new version generated for the element contains an embedded space. 

Symbolic Name: fp_warn_bad_elt_version 

0078 The omnibus element / could not be changed because the 

new subtype is not legal for an omnibus element. 

Symbolic Name: fp_warn_bad_subtype 

Omnibus subtypes must be between 0 and 63. 

0080 The element / could not be undeleted because the relative 

sequence number specified in Seq_Num does not exist. 

Symbolic Name: fp_warn_elt_rel_seq_num_err 

The returned element entry that contains this error code is the member of the 

element/version/type set that has the lowest sequence number. 

0081 The element / is already undeleted. 

Symbolic Name: fp_warn_elt_undeleted 

0082 The element / could not be undeleted because another 

member of the element/version/type set is undeleted and Allow_Deletion does 

not allow its deletion. 

Symbolic Name: fp_warn_elt_delete_not_allowed 

A.2. Errors 

Errors are grouped into the following categories: 

• Calling program errors 

A–4 7830 9796–013

• Execution I/O errors 

• Execution errors other than I/O errors—all file types 

• Execution errors other than I/O errors—sequential-access files 

• Execution errors other than I/O errors—random-access files 

• Execution errors other than I/O errors—program files 

• Errors associated with assigning and freeing files 

• Errors associated with the PACK_PF function 

A.2.1. Calling Program Errors 


1002 Calling Program Error: The value specified for Qualifier in the file identifier with 

index is not legal. For the Acq_File_List function, this error 

indicates that the Qualifier specified in the function packet is not legal. For the 

Chg_File_Name function, if index is 0 this error indicates that the New_Qualifier 

specified in the function packet is not legal. 

Symbolic Name: fp_err_bad_qualifier 

The qualifier must be 1 to 12 characters in length, left justified, space filled or 

null terminated. It must be composed from the characters A – Z, 0 – 9, $, -. A 

value of all spaces or all nulls is also legal. For the Acq_File_List function, the 

qualifier can also contain the wild-card characters (? and *). 

1003 Calling Program Error: The value specified for Filename in the file identifier with 


indicates that the Filename specified in the function packet is not legal. For the 

Chg_File_Name function, if index is 0, this error indicates that the New_Filename 

specified in the function packet is not legal. 

Symbolic Name: fp_err_bad_filename 

The file name must be 1 to 12 characters in length, left justified, space filled or 

null terminated. It must be composed from the characters A – Z, 0 – 9, $, -. A 

value of all spaces or all nulls is not legal. For the Acq_File_List function, the file 

name can also contain the wild-card characters (? and *). Also, in this context, a 

null value is legal. 

7830 9796–013 A–5


1005 Calling Program Error: The value specified for Directory_Id in the file identifier 

with index is not legal. For the Acq_File_List function, this error 

indicates that the Directory_Id specified in the function packet is not legal. 

Symbolic Name: fp_err_bad_directory_id 

The only legal values for Directory_Id are null, STD, and SHARED. A value of all 

spaces is also allowed in the file identifier only. The value SHARED is allowed 

only if Multi-Host File Sharing (MHFS) is configured on the system. 

1006 Calling Program Error: The value specified for F_Cycle_Type in the file identifier 

with index is not legal. For the Acq_File_List function, this error 

indicates that the value specified for F_Cycle_Type in the function packet is not 

legal. 

Symbolic Name: fp_err_bad_f_cycle_type 

The only legal values for F_Cycle_Type are unspecified (0), abs (1), and rel (2). 

1007 Calling Program Error: The value specified for F_Cycle in the file identifier with 


indicates that the value specified for F_Cycle in the function packet is not legal. 

Symbolic Name: fp_err_bad_f_cycle 

When F_Cycle_Type = unspecified (0), F_Cycle must be zero. When 

F_Cycle_Type = abs (1), F_Cycle must be between 1 and 999 inclusive. When 

F_Cycle_Type = rel (2), F_Cycle must be between -31 and 1 inclusive. 

1017 Calling Program Error: A value was specified for F_Cycle in the file identifier 

with index . A specific F-cycle cannot be specified for the 

function you requested, because that function operates on all files in the Fcycle 

series. 

Symbolic Name: fp_err_unalwd_f_cycle 

1041 PCFP Internal Error 

Symbolic Name: fp_err_fct_pkt_range 

The function packet parameter supplied to PCFP extends outside of the 

address range MIN_DATA_ADDR to MAX_DATA_ADDR. Note that a few 

functions have a different address range, as documented in the work area 

descriptions in Sections 3 – 10. For compiler calling programs, this error 

indicates a problem with the interface routine. 


Symbolic Name: fp_err_file_id_range 

A file identifier parameter supplied to PCFP extends outside of the address 

range MIN_DATA_ADDR to MAX_DATA_ADDR. Note that a few functions 

have a different address range, as documented in the work area descriptions in 

Sections 3 – 10. For compiler calling programs, this error indicates a problem 

with the interface routine. 

A–6 7830 9796–013


1043 Calling Program Error: The total size of the return area and the work area 

exceeds the maximum allowed. 

Symbolic Name: fp_err_work_area_range 

The work area parameter supplied to PCFP extends outside of the address 

range MIN_DATA_ADDR to MAX_DATA_ADDR. For compiler calling programs, 

this error indicates the total size of the return area and work area exceeds 

approximately 238,000 words. Note that a few functions have a different 

address range and maximum return area and work area size, as documented in 

the work area descriptions in Sections 3 – 10. 

1044 Calling Program Error: The total size of the return area and the work area 

exceeds the maximum allowed. 

Symbolic Name: fp_err_return_area_range 

The return area parameter supplied to PCFP extends outside of the address 

range MIN_DATA_ADDR to MAX_DATA_ADDR. For compiler calling programs, 

this error indicates the total size of the return area and work area exceeds 

approximately 238,000 words. Note that a few functions have a different 

address range and maximum return area and work area size, as documented in 

the work area descriptions in Sections 3 – 10. 


Symbolic Name: fp_err_stack_range 

The PLUS stack for PCFP extends outside of the address range 

MIN_DATA_ADDR to MAX_DATA_ADDR. Note that a few functions have a 

different address range, as documented in the work area descriptions in 




Symbolic Name: fp_err_stack_size 

The PLUS stack for PCFP is smaller than the 400 words required. For compiler 

calling programs, this error indicates a problem with the interface routine. 


Symbolic Name: fp_err_desc_area_range 

The descriptor return area parameter supplied to PCFP extends outside of the 

address range of MIN_DATA_ADDR to MAX_DATA_ADDR. For compiler 

calling programs, this error indicates a problem with the interface routine. 

7830 9796–013 A–7



Symbolic Name: fp_err_work_space_range 

The PLUS work space for PCFP extends outside of the address range of 

MIN_DATA_ADDR to MAX_DATA_ADDR. Note that a few functions have a 

different address range, as documented in the work area descriptions in 



1050 Calling Program Error: An unused portion of a packet passed to PCFP contains a 

nonzero value. 

Symbolic Name: fp_err_nonzero_filler 

All such items must be initialized to zero by the caller. 

1052 Calling Program Error: The value specified for Interface_Level in the function 

packet or file identifier packet is illegal. 

Symbolic Name: fp_err_bad_interface_level 

The Interface_Level for file identifier packets is described in 2.3. The 

Interface_Level for the generic part of the function packet is described in 2.4.1. 

The individual function packet documentation in Sections 3 – 10 describes the 

most current interface level for each function that supports interface levels 

other than fp_interface_level_1. 


Symbolic Name: fp_err_no_work_area 

The pointer to the work area (last parameter) is null. For compiler calling 

programs this error indicates a problem with the interface routine. 

1054 Calling Program Error: The value specified for Work_Area_Size in the function 

packet is smaller than the minimum required by the function. 

Symbolic Name: fp_err_small_work_area 

1055 Calling Program Error: The value specified for Return_Area_Size in the function 

packet is > 0 but the Return Area parameter is null. 

Symbolic Name: fp_err_bad_return_area 

A–8 7830 9796–013


1056 Calling Program Error: The value specified for Work_Area_Size in the PREP_PF 

function packet is smaller than the amount required for 

relocatable entry points. 

Symbolic Name: fp_err_small_prep_pf_work_area 

The program file has the number of relocatable entry points shown in the 

message and contained in the Aux_Error_Code item in the generic part of the 

function packet. Use this value and the formula described in 8.5.4 to calculate 

the required value for Work_Area_Size. Call the PREP_PF function again with 

this value. 

1062 Calling Program Error: The value specified for Return_Area_Size in the function 

packet is smaller than the minimum required by the function. 

Symbolic Name: fp_err_small_return_area 

1072 Calling Program Error: The value specified for Num_Dest_Files in the function 

packet is not legal. 

Symbolic Name: fp_err_bad_num_dest_files 

Currently, the only legal value for Num_Dest_Files is 1. 

1073 The file with index is not a Random-Access File, but the function 

requires such a file. 

Symbolic Name: fp_err_not_raf 

1074 The file with index is not a Sequential-Access File, but the 

function requires such a file. 

Symbolic Name: fp_err_not_saf 

1201 Calling Program Error: The value specified for Dest_Format in the function 


Symbolic Name: fp_err_bad_format 

The only legal value for Dest_Format is furpur (1). 

1202 Calling Program Error: The value specified for On_End_Of_File or 

On_End_Of_Dest_File in the function packet is not legal. 

Symbolic Name: fp_err_bad_on_end_dest 

The only legal values are rtn_error (0), extend_to_blank_volume (1), and 

solicit_opr (1). 

7830 9796–013 A–9


1203 Calling Program Error: The value specified for On_End_Of_File or 

On_End_of_Source_File in the function packet is not legal. 

Symbolic Name: fp_err_bad_on_end_source 

The only legal values are rtn_error (0), extend_to_blank_volume (1), and 

solicit_opr (1). 


Symbolic Name: fp_err_vol_subr_required 


Symbolic Name: fp_err_vol_subr_unalwd 


Symbolic Name: fp_err_bad_data_size 


Symbolic Name: fp_err_aux_info_unalwd 

1208 Calling Program Error: The item Synchronize can be TRUE only if 

Interface_Level is at least . 

Symbolic Name: fp_err_bad_synchronize 

1209 Calling Program Error: The item Write_Obsolete_Variant can be TRUE only if 

the size of Dest_Block_Size is 0 or 1. 

Symbolic Name: fp_err_obsolete_variant_unalwd 

The obsolete variant of the FURPUR tape format requires that each tape block 

contains one mass storage track. 

1210 Calling Program Error: The item Return_Block_Id can be TRUE only if 

Interface_Level is at least 2. 

Symbolic Name: fp_err_bad_return_block_id 

1211 Calling Program Error: The value specified for On_Conflict in the function packet 

is not legal. 

Symbolic Name: fp_err_bad_on_conflict 

The only legal values for On_Conflict are do_not_copy (0), delete_original (1), 

and copy_if_newer (2). 

1212 Calling Program Error: The value specified for Info_to_Return in the function 


Symbolic Name: fp_err_bad_info_to_return 

The only legal values for Info_to_Return are none (0), error_only (1), 

nonerror_only (2), and all_info (3). 

A–10 7830 9796–013


1213 Calling Program Error: The value specified for Info_Detail in the function packet 

is not legal. 

Symbolic Name: fp_err_bad_info_detail 

The only legal values for Info_Detail are short (0) and long (1). The functions 

Acq_File_Info and Acq_File_List also allow the value complete (2). 

1214 Calling Program error: The value specified for Elt_Name, New_Elt_Name or 

Dest_Elt_Name in the function packet is not legal. 

Symbolic Name: fp_err_bad_elt_name 

The Elt_Name, New_Elt_Name and Dest_Elt_Name must be 1 to 12 characters 

in length, left justified, space filled or null terminated. It must be composed 

from the characters A – Z, 0 – 9, $, -. A value of all nulls is legal. A value of all 

spaces is not legal. See the function description for the use of the wild-card 

characters (- and *). 

1215 Calling Program Error: The value specified for Elt_Version, New_Elt_Version or 

Dest_Elt_Version in the function packet is not legal. 

Symbolic Name: fp_err_bad_elt_version 

The Elt_Version must be 1 to 12 characters in length, left justified, space filled 

or null terminated. It must be composed from the characters A – Z, 0 – 9, $, -. 

A value of all spaces is legal. See the function description for the use of all 

nulls and wild-card characters (? and *). 

1216 Calling Program Error: The value specified for Cycle_Type in the function packet 

is not legal. 

Symbolic Name: fp_err_bad_cycle_type 

The only legal values for Cycle_Type are unspecified (0), abs (1), and rel (2). 

1217 Calling Program Error: The value specified for Cycle_Num in the function packet 

is not legal. 

Symbolic Name: fp_err_bad_cycle_num 

When Cycle_Type = unspecified (0), Cycle_Num must be zero. When 

Cycle_Type = abs (1), Cycle_Num must be between 0 and 62 inclusive. When 

Cycle_Type = rel (2), Cycle_Num must be between -62 and 0 inclusive. 

1218 Calling Program Error: The value specified for Dest_Sym_Subtype, 

Dest_Omn_Subtype, or New_Omn_Sym_Subtype in the function packet is not 

legal. 

Symbolic Name: fp_err_bad_subtype 

Symbolic subtypes must be between 0 and 66. Omnibus subtypes must be 

between 0 and 63. Absolute subtypes must be between 0 and 4. 

1219 Calling Program Error: The value specified for New_Cycle_Limit in the function 


Symbolic Name: fp_err_bad_cycle_limit 

The value of the New_Cycle_Limit must be between 0 and 63 inclusive. 

7830 9796–013 A–11


1221 Calling Program Error: The value specified for Storage_to_Release in the 

function packet is not legal. 

Symbolic Name: fp_err_bad_storage_to_release 

The legal values for Storage_to_Release are none (0), all_but_initial_reserve (1), 

and all_storage (2). 

1222 Calling Program Error: The value specified for Pack_Method in the function 


Symbolic Name: fp_err_bad_pack_method 

1224 Calling Program Error: The value specified for EP_Name in the function packet 

is not legal. 

Symbolic Name: fp_err_bad_ep_name 

Either the EP_Name contains illegal characters, or a value other than zero was 

specified and the value of Text_Type was given a value other than ASCII (1). 

The EP_Name must be 1 to 32 characters in length, left justified, space filled or 

null terminated. The EP_Name may contain the wild-card characters (? and *). 

A value of all nulls is legal. A value of all spaces is not legal. 

1225 Calling Program Error: The value specified for Proc_Name in the function packet 

is not legal. 

Symbolic Name: fp_err_bad_proc_name 

The Proc_Name must be 1 to 30 characters in length, left justified, space filled 

or null terminated. The name can be longer than 12 characters only if 

Proc_Table is set to cobol_proc. It must be composed from the legal 

characters for procedure names. The Proc_Name may also contain the wildcard 

characters (? and *). A value of all nulls is legal. A value of all spaces is 

not legal. 

1227 Calling Program Error: The value specified for Proc_Table in the function packet 

is not legal. 

Symbolic Name: fp_err_bad_proc_table 

The only legal values for Proc_Table are masm_proc (2), cobol_proc (3), and 

ftn_pls_proc (4). 

1228 Calling Program Error: The value specified for Text_Type in the function packet 

is not legal. 

Symbolic Name: fp_err_bad_text_type 

The only legal values for Text_Type are no_constraint (0), ASCII (1) and Kanji (3). 

A–12 7830 9796–013


1229 Calling Program Error: The value specified for SCS_Conformance in the function 


Symbolic Name: fp_err_bad_scs_conformance 

The only legal values for SCS_Conformance are no_constraint (0), none (1), 

loose (16), and strict (17). 

1231 Calling Program Error: The value specified for Char_Type in the function packet 

is not legal. 

Symbolic Name: fp_err_bad_char_type 

The only legal values for Char_Type are both (0), ASCII (1), and Fieldata (2). 

1232 Calling Program Error: The value specified for Deletion in the function packet is 

not legal. 

Symbolic Name: fp_err_bad_deletion 

The only legal values for Deletion are undeleted (0), deleted (1), and both (2). 

1233 Calling Program Error: The value specified for Min_Date_Time in the function 

packet exceeds the corresponding value for Max_Date_Time. 

Symbolic Name: fp_err_bad_date_time 

For the function Acq_File_List, this error can refer to the values for 

Create_Date_Time or Ref_Date_Time or Backup_Date_Time. 

1234 Calling Program Error: The value specified for Min_Seq_Num in the function 

packet exceeds the value for Max_Seq_Num. 

Symbolic Name: fp_err_bad_seq_num 

1235 Calling Program Error: The value specified for Min_Size in the function packet 

exceeds the value for Max_Size. 

Symbolic Name: fp_err_bad_seq_num 

1241 Calling Program Error: The value specified for EP_Type in the function packet is 

not legal. 

Symbolic Name: fp_err_bad_ep_type 

The legal values for EP_Type are rel_ep (1), om_ep (2), and both (3). 

1245 Calling Program Error: The value specified for Action in the function packet is 

not legal. 

Symbolic Name: fp_err_bad_action 

The legal values for Action are overcopy (0) and must_be_empty (1). 

7830 9796–013 A–13


1247 Calling Program Error: The value specified for Seq_Num_Type in the function 


Symbolic Name: fp_err_bad_seq_num_type 

The only legal values for Seq_Num_Type are rel (0) and abs (1). 

1248 Calling Program Error: The value specified for Seq_Num in the function packet 

is not legal. 

Symbolic Name: fp_err_bad_elt_seq_num 

When Seq_Num_Type = rel (0), Seq_Num must be between -26,145 and 0 

inclusive. When Seq_Num_Type = abs (1), Seq_Num must be between 1 and 

26,146 inclusive. 

1249 Calling Program Error: When Seq_Num_Type is set to abs in the function 

packet, Elt_Name and Elt_Version must have null values and Abs_Type, 

Omn_Type, Rel_Type, Sym_Type, the Omn_Sym_Subtype array and the 

Abs_Subtype array must all be FALSE. 

Symbolic Name: fp_err_elt_selection_conflict 

Elt_Name, Elt_Version, Abs_Type, Omn_Type, Rel_Type, Sym_Type, 

Omn_Sym_Subtype or Abs_Subtype can only be specified by the calling 

program when Seq_Num_Type is set to rel (0) and when Seq_Num contains a 

relative sequence number (-26,145 through 0, inclusive). 

1250 Calling Program Error: The value specified for Site_Info in the function packet 

must be zero when Select_on_Site_Info or Change_Site_Info is not set to 

TRUE. 

Symbolic Name: fp_err_bad_site_info 

1251 Calling Program Error: The value specified for Rollout_Prohibited in the function 


Symbolic Name: fp_err_bad_rollout_prohibited 

The legal values for Rollout_Prohibited are no_chg (0), set_off (1), and set_on 

(2). 

1252 Calling Program Error: The value specified for Read_Only in the function packet 

is not legal. 

Symbolic Name: fp_err_bad_read_only 

The legal values for Read_Only are no_chg (0), set_off (1), and set_on (2). 

1253 Calling Program Error: The value specified for Write_Only in the function packet 

is not legal. 

Symbolic Name: fp_err_bad_write_only 

The only legal values for Write_Only are no_chg (0), set_off (1), and set_on (2). 

A–14 7830 9796–013


1254 Calling Program Error: The value specified for Directory_Disable in the function 


Symbolic Name: fp_err_bad_directory_disable 

The only legal values for Directory_Disable are no_chg (0), set_off (1), and 

set_on (2). 

1255 Calling Program Error: The value specified for Write_Disable in the function 


Symbolic Name: fp_err_bad_write_disable 

The only legal values for Write_Disable are no_chg (0), set_off (1), and set_on 

(2). 

1256 Calling Program Error: The value specified for Backup_Disable in the function 


Symbolic Name: fp_err_bad_backup_disable 

The only legal values for Backup_Disable are no_chg (0), set_off (1), and set_on 

(2). 

1257 Calling Program Error: The value specified for Cache_Disable in the function 


Symbolic Name: fp_err_bad_cache_disable 

The only legal values for Cache_Disable are no_chg (0), set_off (1), and set_on 

(2). 

7830 9796–013 A–15


1258 Calling Program Error: The value specified for Init_Program_File or 

Init_Dest_File in the function packet is not legal. 

Symbolic Name: fp_err_bad_init_prog_file 

The legal values for Init_Program_File or Init_Dest_File are none (0), pf (1), lpf 

(2), standard_lepf (3), and large_lepf (4). For the COPY_ELT function 

Init_Dest_File also has the legal value source_file_type (5). 

1261 Calling Program Error: The value specified for Project_Id or Account_Id in the 


Symbolic Name: fp_err_bad_project_account_id 

The Project_Id or Account_Id must be 1 to 12 characters in length, left justified, 

space filled or null terminated. The Project_Id must be composed from the 

characters A – Z, 0 – 9, hyphen ( - ), and the dollar sign ($). The Account_Id 

must be composed from the characters A – Z, 0 – 9, hyphen ( - ), and the period 

( . ). A value of null is legal. A value of all spaces is not legal. For the 

Acq_File_List function, the Project_Id or Account_Id may also contain the 

wild-card characters (? and *). 

1265 Calling Program Error: The value specified for Max_F_Cycles in the function 


Symbolic Name: fp_err_bad_max_f_cycles 

The value for Max_F_Cycles must be between 0 and 32. 

1271 Calling Program Error: The value specified for Privacy in the function packet is 

not legal. 

Symbolic Name: fp_err_bad_privacy 

The only legal values for Privacy are no_chg (0), private (1), semiprivate (2), and 

public (3). 

1272 Calling Program Error: The value specified for New_Read_Key or for 

New_Write_Key in the function packet is not legal. 

Symbolic Name: fp_err_bad_new_key 

The values for New_Read_Key and New_Write_Key must be 0 to 6 characters 

in length, left justified, and either space filled or null terminated. They can be 

composed of any character except the following: the comma ( , ), the slash ( / ), 

the semi-colon ( ; ), and the period ( . ). A value of all nulls is legal and indicates 

the key is not to be changed. A value of all spaces is legal and indicates the 

key is to be removed. 

A–16 7830 9796–013


1275 Calling Program Error: The value specified for ACR_Name in the function packet 

is not legal. 

Symbolic Name: fp_err_bad_acr_name 

The value for ACR_Name must be 1 to 6 characters in length, left justified, and 

either space filled or null terminated. It must be the name of an existing ACR 

composed from the characters A – Z, 0 – 9. The ACR must be owned by the 

user-id of the run calling PCFP. A value of null is not legal if Privacy is set to 

semiprivate. A value of null is required if Privacy is set to any value except 

semiprivate. 

1276 Calling Program Error: The value specified for File_Owner_User_Id in the 


Symbolic Name: fp_err_bad_file_owner_user_id 

If Chg_File_Owner_User_Id is FALSE, File_Owner_User_Id cannot be specified. 

The values for File_Owner_User_Id must be 0 to 6 characters in length, left 

justified, and either space filled or null terminated. They must be composed 

from the characters A – Z, 0 – 9. A value of all nulls is legal and will cause the 

file to be unowned if Chg_File_Owner_User_Id is set to TRUE. This item must 

be all nulls unless Chg_File_Owner_User_Id is set to TRUE. 

1277 Calling Program Error: The value specified for Clearance_Level in the function 


Symbolic Name: fp_err_bad_clearance_level 

If Chg_Clearance_Level is FALSE, Clearance_Level cannot be specified. The 

legal values for Clearance_Level are between 0 and 62 inclusive. 

1281 Calling Program Error: The value specified for Search_Set in the function packet 

is not legal. 

Symbolic Name: fp_err_bad_search_set 

The only legal values for Search_Set are asgd_to_run (1), known_to_run (2) and 

catalog_directory (3). 

1282 Calling Program Error: The value specified for Lifetime in the function packet is 

not legal. 

Symbolic Name: fp_err_bad_lifetime 

The only legal values for Lifetime are no_constraint (0), cataloged (1) and 

temporary (2). 

1283 Calling Program Error: When both a Min_F_Cycle_Type and a 

Max_F_Cycle_Type are specified, either both must be abs (1) or both must be 

rel (2). 

Symbolic Name: fp_err_incompat_f_cycle_types 

7830 9796–013 A–17


1284 Calling Program Error: The value specified for Equip_Type in the function packet 

is not legal. 

Symbolic Name: fp_err_bad_equip_type 

The legal values for Equip_Type are none (0), mass_storage (1), tape (2), and 

miscellaneous (3). 

1285 Calling Program Error: A selection attribute was specified that is not in the set 

of attributes requested. 

Symbolic Name: fp_err_bad_qualification 

For the Acq_File_List function, an attribute cannot be used to qualify the files 

selected unless the calling program has also specified that the attribute is to be 

included in the information to be returned by the function. 

1286 Calling Program Error: The values specified for Lifetime and Search-Set in the 

function packet are not compatible. 

Symbolic Name: fp_err_incompat_life_srch_set 

When Lifetime has a value of Temporary(2), Search_Set cannot have a value of 

Catalog_Directory(3) since temporary files are never represented in the 

directory of cataloged files. 

1301 Calling Program Error: The value specified for Type_of_Move in the function 


Symbolic Name: fp_err_bad_type_of_move 

The only legal values for Type_of_Move are forward (0), backward (1), 

to_saf_end (2) and to_saf_start (3). 

1302 Calling Program Error: The value specified for Move_Num in the function 

packet is not legal for the Type_of_Move specified. 

Symbolic Name: fp_err_bad_move_num 

Move_Num must be zero if Type_of_Move is to_saf_end or to_saf_start and 

not zero if Type_of_Move is backward. 

1303 Calling Program Error: The value specified for Current_Vol_Only in the function 

packet is not legal for the Type_Of_Move specified. 

Symbolic Name: fp_err_bad_current_vol_only 

Current_Vol_Only must be set to TRUE if the Type_of_Move is backward. 

A–18 7830 9796–013


1304 Calling Program Error: The value specified for Position_At_End_Of_Log_File in 

the function packet is not legal. 

Symbolic Name: fp_err_bad_position_at_end 

Position_At_End_Of_Log_File can be set to TRUE only if Type_of_Move is set 

to backward. 

1305 Calling Program Error: The value specified for Interlock in the function packet is 

not legal. 

Symbolic Name: fp_err_bad_interlock 

Interlock can be set to TRUE only if Type_of_Move is set to to_saf_start. 

1306 Calling Program Error: The value specified for Move_At_End in the function 


Symbolic Name: fp_err_bad_move_at_end 

1307 Calling Program Error: The item Type_Of_Move can have a value of 

To_Block_Id only if Interface_Level is at least 2. 

Symbolic Name: fp_err_bad_to_block_id 

1308 Calling Program Error: The value specified for Move_Block_Id must be zero for 

the Type_Of_Move specified. 

Symbolic Name: fp_err_nonzero_move_block_id 

1309 Calling Program Error: The value specified for Move_Block_Id is not a legal 

block-id. 

Symbolic Name: fp_err_illegal_move_block_id 

This error is most likely to occur when the special block-id value of –1 (octal 

value 0777777777776) or –2 (octal value 0777777777775) is incorrectly used as 

the Move_Block_Id value. The special block-id value of –1 is returned by PCFP 

functions when fast tape access is not supported for the requested tape file. 

The special block-id value of –2 can be returned by the COPY_SAF_RAF and 

MOVE_SAF functions when a labeled tape is positioned to its logical end. The 

error could also occur when the value stored in Move_Block_Id is not a block-id 

returned by a previous RBIDW$ or RBKID$ I/O function. 

7830 9796–013 A–19


1401 Calling Program Error: The value specified for Exclusive_Assign in the function 


Symbolic Name: fp_err_exclusive_required 

Exclusive_Assign is set to FALSE but the requested operation requires 

exclusive assignment of the file. 

1501 Calling Program Error: A subroutine for processing the descriptor on the 

sources tape file was specified without also specifying the item 

Source_Format. 

Symbolic Name: fp_err_src_format_req 

A nonzero value for the item Source_Format is always required whenever a 

subroutine for processing the descriptor on the source tape is specified by 

means of a nonzero value in the item Source_Format. 

1502 Calling Program Error: A virtual address contained in the Src_Desc_Subr or 

Dest_Desc_Subr is illegal in that the BDI portion or the Offset portion is 0. 

Symbolic Name: fp_err_badly_formed_va 

1503 Calling Program Error: The Event_Array has an Event(i) set to TRUE that is not 

supported for this function. 

Symbolic Name: fp_err_bad_event 

1504 Calling Program Error: Event_Array cannot be specified without also specifying 

Caller_Subr. 

Symbolic Name: fp_err_caller_subr_required 

1505 Calling Program Error: Neither Src_Desc_Subr nor Dest_Desc_Subr may be 

specified when Event_Array and Caller_Subr are specified. 

Symbolic Name: fp_err_desc_subr_not_allowed 

1506 Calling Program Error: Caller_Subr cannot be specified without also specifying 

at least one Event(i) as TRUE in the Event_Array. 

Symbolic Name: fp_err_caller_subr_not_allowed 

1507 Calling Program Error: The specified Caller_Subr virtual address is invalid, 

having either a zero BDI or a zero offset. 

Symbolic Name: fp_err_caller_subr_bad_va 

A–20 7830 9796–013

A.2.2. Execution I/O Errors 


2001 Unexpected I/O status was returned by a read (R$) request to 

the file with index . 

Symbolic Name: fp_err_bad_io_r 

2002 Unexpected I/O status was returned by a scatter-read (SCR$) 

request to the file with index . 

Symbolic Name: fp_err_bad_io_scr 

2004 Unexpected I/O status was returned by a multiple-request (MR$) 

read (R$) request to the file with index . 

Symbolic Name: fp_err_bad_io_mr_r 

2005 Unexpected I/O status was returned by a move-forward (MF$) 


Symbolic Name: fp_err_bad_io_mf 

2006 Unexpected I/O status was returned by a move-backward (MB$) 


Symbolic Name: fp_err_bad_io_mb 

2007 Unexpected I/O status was returned by a forward-space-file 

(FSF$) request to the file with index . 

Symbolic Name: fp_err_bad_io_fsf 

2008 Unexpected I/O status was returned by a backward-space-file 

(BSF$) request to the file with index . 

Symbolic Name: fp_err_bad_io_bsf 

2009 Unexpected I/O status was returned by a rewind (REW$) 


Symbolic Name: fp_err_bad_io_rew 

2010 Unexpected I/O status was returned by a release (REL$) request 

to the file with index . 

Symbolic Name: fp_err_bad_io_rel 

7830 9796–013 A–21


2011 Unexpected I/O status was returned by a write (W$) request to 


Symbolic Name: fp_err_bad_io_w 

2012 Unexpected I/O status was returned by a gather-write (GW$) 


Symbolic Name: fp_err_bad_io_gw 


read-backward (RB$) request to the file with index . 

Symbolic Name: fp_err_bad_io_mr_rb 


write (W$) request to the file with index . 

Symbolic Name: fp_err_bad_io_mr_w 

2015 Unexpected I/O status was returned by a write-end-of-file 

(WEF$) request to the file with index . 

Symbolic Name: fp_err_bad_io_wef 

2016 Unexpected I/O status was returned by a mode set (MS$) 


Symbolic Name: fp_err_bad_io_ms 

2017 Unexpected I/O status was returned by a set mode (SM$) 


Symbolic Name: fp_err_bad_io_sm 

2018 Unexpected I/O status was returned by a read block-id before 

write (RBIDW$) request to the file with index . 

Symbolic Name: fp_err_bad_io_rbidw 

2019 Unexpected I/O status was returned by a read block-id (RBKID$) 


Symbolic Name: fp_err_bad_io_rbkid 

2020 Unexpected I/O status was returned by a locate block-id (LBLK$) 


Symbolic Name: fp_err_bad_io_lblk 

2021 Unexpected I/O status was returned by a file update 

wait/synchronize (FSAFE$) request to the file with index . 

Symbolic Name: fp_err_bad_io_fsafe 

A–22 7830 9796–013


2022 The Words_Transferred value returned by a scatter-read (SCR$) I/O request 

was different than PCFP expected for the file with index . 

Symbolic Name: fp_err_bad_word_count_scr 

2023 The Words_Transferred value returned by a gather-write (GW$) I/O request was 

different than PCFP expected for the file with index . 

Symbolic Name: fp_err_bad_word_count_gw 

2024 The Words_Transferred value returned by a multiple-request (MR$) I/O request 

was different than PCFP expected for the file with index . 

Symbolic Name: fp_err_bad_word_count_mr 

A.2.3. Execution Errors Other than I/O Errors—All File Types 

2101 The file is not or cannot be assigned as readable. 

Symbolic Name: fp_err_unreadable_file 

2102 The file is not or cannot be assigned as writable. 

Symbolic Name: fp_err_unwriteable_file 

2103 The source file and the destination file are the same file and the requested 

function does not allow them to be the same file. 

Symbolic Name: fp_err_same_files 

2120 Error status was returned by the ER INFO$ function MEDTYP$ 

for the file with index . 

Symbolic Name: fp_err_bad_info_medtyp 

2121 Error status was returned by the ER INFO$ function INFILE$ for 


Symbolic Name: fp_err_bad_info_infile 

2122 Error status was returned by the ER INFO$ function FFILEX$ for 


Symbolic Name: fp_err_bad_info_ffilex 

2123 Error status was returned by the ER INFO$ function FBLKSX$ 


Symbolic Name: fp_err_bad_info_fblksx 

7830 9796–013 A–23


2124 Error status was returned by the ER INFO$ function FEQP$ for 


Symbolic Name: fp_err_bad_info_feqp 

2125 Error status was returned by the ER INFO$ function ASGCNT$ 


Symbolic Name: fp_err_bad_info_asgcnt 

2126 Error status was returned by the ER INFO$ function FREELX$ 


Symbolic Name: fp_err_bad_info_freelx 

2127 Error status was returned by the ER INFO$ function LNAME$ for 


Symbolic Name: fp_err_bad_info_lname 

2128 Error status was returned by the ER INFO$ function EQUIP$ for 


Symbolic Name: fp_err_bad_info_equip 

2129 Error status was returned by the ER INFO$ function MODE$ for 


Symbolic Name: fp_err_bad_info_mode 

2130 Error status was returned by the ER INFO$ function RING$ for 


Symbolic Name: fp_err_bad_info_ring 

2131 Error status was returned by ER FITEM$ for the file with index 

. 

Symbolic Name: fp_err_bad_fitem 

2132 Information returned by FITEM$ indicated that the temporary file with index 

was not assigned to the run. 

Symbolic Name: fp_err_temp_no_equip 

A FITEM$ equipment code of 00, meaning not assigned was returned for a 

temporary file. This is logically inconsistent, since a temporary file only exists 

while it is assigned to a run. 

A–24 7830 9796–013


2136 Unexpected error status was returned by ER SUVAL$. 

Symbolic Name: fp_err_bad_suval 

The error status is from S6 of word 0 of the SUVAL$ function packet. Refer to 

the Security Administration for ClearPath OS 2200 Help for interpretation of the 

status. 

2137 Unexpected function return status was returned by ER SUVAL$. 

Symbolic Name: fp_err_bad_suval_func 

The function return status is from T2 of word 010, 011 or 012 of a format 1 

SUVAL$ function packet or from T2 of word 012, 013 or 014 of a format 2 

SUVAL$ function packet. Refer to the Security Administration for ClearPath OS 

2200 Help for interpretation of the status. 

2141 System Error: PCFP detected an invalid Lead Item in the Master File Directory. 

Symbolic Name: fp_err_bad_mfd_lead_item 

The identifier code for the Lead Item, which was read from the Master File 

Directory, is not an identifier code for a Lead Item. It is likely that at least part 

of the Master File Directory has been corrupted. 

2142 System Error: PCFP detected an invalid Main Item in the Master File Directory. 

Symbolic Name: fp_err_bad_mfd_main_item 

The identifier code for the Main Item, which was read from the Master File 

Directory, is not an identifier code for a Main Item. It is likely that at least part 


2143 System Error: PCFP detected an invalid Shared Item in the Master File 

Directory. 

Symbolic Name: fp_err_bad_mfd_shared_item 

The identifier code for the Shared Item, which was read from the Master File 

Directory, is not an identifier code for a Shared Item. It is likely that at least part 


2144 System Error: PCFP detected invalid tape file information in the Program 

Control Table (PCT). 

Symbolic Name: fp_err_bad_pct_tape_info 

7830 9796–013 A–25


2145 System Error: PCFP detected invalid or inconsistent information in the Name 

Section portion of the Program Control Table (PCT). 

Symbolic Name: fp_err_bad_pct_name_section 

This error is detected by the ACQ_FILE_INFO and ACQ_FILE_LIST functions, 

which directly examine the Program Control Table (PCT). This error can occur if 

the calling program is multi-activity and if more than one activity is calling PCFP 

functions or making other facilities requests that add internal or external 

filenames to the run (@USE or @ASG) or that remove internal or external 

filenames from the run (@FREE). It can also occur if the PCT Name Section of 

the run calling PCFP has overflowed or is close to overflowing. 

2151 System Error: Unrecognized equipment mnemonic was returned 

by the ER INFO$ function FEQP$ for the file with index . 

Symbolic Name: fp_err_unknown_equip_mnemonic 

Although the equipment mnemonic is printed in octal, it should be interpreted 

as Fieldata. 

2160 The file with index is not a cataloged file, but the called function 

requires such a file. 

Symbolic Name: fp_err_not_cataloged 

2161 The file with index is not a mass storage file, but the called 

function requires such a file. 

Symbolic Name: fp_err_not_ms 

2162 The file with index is not a sector-addressable mass storage file, 

but the called function requires such a file. 

Symbolic Name: fp_err_not_sector_ms 

2166 Your run does not have sufficient privileges to perform the requested operation. 

Symbolic Name: fp_err_not_privileged 


Symbolic Name: fp_err_sort_err 

2175 The name change could not be completed for this shared file because the 

name change capability is not available on all hosts or because the file sharing 

version is not Network file sharing. 

Symbolic Name: fp_err_sharing_incompatibility 

A–26 7830 9796–013


2176 The name change could not be completed because a file with the requested 

qualifier and file name already exists. 

Symbolic Name: fp_err_new_name_exists 

2177 The name change could not be completed because one or more files of the 

F-cycle series are either unloaded or are on a symbiont queue. 

Symbolic Name: fp_err_unloaded_or_on_queue 

2178 The name change could not be completed for this removable disk file because 

it resides on or spans a pack that is in the DN,PACK state. 

Symbolic Name: fp_err_removable_pack_down 

2181 PCFP did not make the requested change, because fewer F-cycles would be 

retained than currently exist, and the function packet indicated that no 

currently-existing F-cycles are to be deleted. 

Symbolic Name: fp_err_too_many_f_cycles 

2182 PCFP did not make the requested change, because the change requires 

deletion of F-cycle +0 without eliminating the entire F-cycle series. 

Symbolic Name: fp_err_f_cycle_conflict 

PCFP issues this error if: 

• The F-cycle series contains a file that is to-be-cataloged with an absolute 

F-cycle number above that of F-cycle +0 of the series 

• PCFP needs to delete F-cycle +0 in order to perform the change 

The file to-be-cataloged can be assigned either by your run or by another run. 

PCFP also issues this error if: 

• The file identifier you specified contains an internal file name 

• The internal file name is attached to a specific F-cycle of the F-cycle series 

• PCFP needs to delete this F-cycle in order to perform the change 

For this function, you must not specify an internal file name attached to a 

specific F-cycle. 

2183 PCFP did not make the requested change, because the change requires the 

deletion of a file that is currently on a symbiont queue. The absolute F-cycle of 

the file on the symbiont queue is . 

Symbolic Name: fp_err_f_cycle_symmed 

7830 9796–013 A–27



deletion of a file that cannot be assigned exclusively to your run. The absolute 

F-cycle of the file that cannot be assigned exclusively to your run is 

. 

Symbolic Name: fp_err_cant_asg_f_cycle 


deletion of a file that PCFP could not delete. The absolute F-cycle of the file 

that could not be deleted is . 

Symbolic Name: fp_err_cant_delete_f_cycle 

The item F_Cycles_Deleted in the function packet indicates the number of 

other files in the same F-cycle series (if any) that were deleted successfully 

while PCFP attempted to perform the requested change. 


EXEC security features to be configured, and they are not configured. 

Symbolic Name: fp_err_security_not_configured 

2191 System Error: PCFP is unable to create the data bank it requires to do its basic 

mode processing. 

Symbolic Name: fp_err_cant_make_bank 

2192 System Error: PCFP is unable to release the data bank it created to do its basic 

mode processing. 

Symbolic Name: fp_err_cant_free_bank 

A–28 7830 9796–013


Sequential-Access Files 


2201 A track sequence number error was detected while reading the source file. 

Symbolic Name: fp_err_seq_num_err 

Execution of the function was terminated, as requested by the value of FALSE 

for Process_Track_Seq_Errors in the function packet. The sequence number of 

the track causing the error can be found in item Loc_First_Track_Seq_Error in 

the function packet. This error frequently indicates invalid or corrupted data on 

the tape file. 

2202 A checksum error was detected while reading the source file. 

Symbolic Name: fp_err_checksum_err 

Execution of the function was terminated, as requested by the value FALSE for 

Process_Checksum_Errors in the function packet. The sequence number of 

the block causing the error can be found in item Loc_First_Checksum_Error in 

the function packet. This error frequently indicates invalid or corrupted data on 

the tape file. 

2205 The copy operation could not be performed, because the source file is written 

in a format not compatible with the requested format for the destination file. 

Symbolic Name: fp_err_format_incompat 


Symbolic Name: fp_err_incompat_blocksize 

The copy operation could not be performed, because the block size 

requirements of the files involved in the copy operation are not compatible. 

Currently, this error cannot be issued, since no combination of file types now 

handled by PCFP is incompatible in this fashion. 

2211 The source tape file was written in FURPUR format which does not match the 

format specified in the function packet. 

Symbolic Name: fp_err_wrong_format_furpur 

2212 The source tape file was written in SDF format which does not match the 


Symbolic Name: fp_err_wrong_format_sdf 

2213 The source tape file was written in FAS1R1 format which does not match the 


Symbolic Name: fp_err_wrong_format_fas1r1 

2214 The source tape file was written in FAS2R1 format which does not match the 


Symbolic Name: fp_err_wrong_format_fas2r1 

7830 9796–013 A–29


2215 The format of the logical file on the source tape file could not be recognized by 

PCFP. 

Symbolic Name: fp_err_unknown_format 

2216 The source tape file is a conditioned file. The site is not authorized to access 

the file. 

Symbolic Name: fp_err_conditioned_file. 

The source tape file is a conditioned file created by SOLAR. Individual files on 

a conditioned tape can only be copied if the keys contained in the file match 

keys that the site has installed. This error code indicates that the site does 

not have installed the keys that match this file. The file is not copied. 

2221 The requested operation was terminated because the source tape file is 

positioned at a logical file fragment continued from another volume. 

Symbolic Name: fp_err_continuation_fragment 

You cannot copy the current logical file from the source tape, because the 

initial portion of this logical file is on another volume. 

2222 The descriptor for the logical file on the source tape file is badly formed. 

Symbolic Name: fp_err_ill_formed_desc 

2223 A swap of the source tape file was attempted and the logical file descriptor 

found on the continued fragment of the logical file does not indicate a 

continued-file fragment as it should. 

Symbolic Name: fp_err_bad_continuation_desc 

2230 The specified block size exceeds the maximum for a destination file. The 

largest block size that can be written to the destination tape file is 

words. 

Symbolic Name: fp_err_block_size_too_big 

The destination tape file has a limit on the size of the physical blocks that can 

be written to it. The block size specified in the function packet exceeds that 

limit. 

2231 The block size specified in the function packet is not legal for the format of the 

file to be written to the destination file. 

Symbolic Name: fp_err_illegal_block_size 

2232 The block size you specified in the function packet does not match the block 

size with which the source file was written. 

Symbolic Name: fp_err_wrong_block_size 

If a block size of zero is specified in the function packet, PCFP will copy the 

file regardless of the block size with which it was written. 

2233 The source tape file cannot be read because it is positioned at its logical end. 

Symbolic Name: fp_err_at_logical_end 

A–30 7830 9796–013

There are no further logical files on the tape. You must move the tape 

backward before you can read another logical file from the tape. 


2235 The destination tape file is not positioned immediately following an EOF mark. 

Symbolic Name: fp_err_not_after_eof 

The tape must be positioned immediately following an EOF mark before you 

can copy another logical file to it. 

2251 The tape could not be moved completely as you requested, because a swap 

would have been required, but Current_Vol_Only in the function packet was 

set to TRUE. 

Symbolic Name: fp_err_past_end_of_vol 

When Current_Vol_Only is set to TRUE, no reel swaps are to be done during 

the Move operation. The Move has been completed only to the end of the 

current volume, so that the tape has been positioned at the last logical file on 

that volume. 

2252 The end of the last volume of the tape file with index was 

encountered and extension of the file to another volume was prohibited. 

Symbolic Name: fp_err_swap_beyond_end 

PCFP did not attempt to extend the tape file to another volume because the 

value of On_End_of_File in the function packet was set to error. 


Symbolic Name: fp_err_supply_vol 


Symbolic Name: fp_err_verify_vol 


Symbolic Name: fp_err_caller_subr 

2257 The system operator aborted the attempted swap beyond the last volume of 

the tape file with index . 

Symbolic Name: fp_err_operator_aborted_swap 

The attempted swap was aborted due to operator key-in. 

2261 The caller subroutine called by PCFP to process the source file logical file 

descriptor returned an error code to PCFP indicating that it could not 

successfully complete its operation. 

Symbolic Name: fp_err_src_desc_decode 

2262 The caller subroutine called by PCFP to process the destination file logical file 

descriptor returned an error code to PCFP indicating that it could not 


7830 9796–013 A–31


Symbolic Name: fp_err_desc_subr_err 

2265 The caller subroutine called by PCFP to process the source file swap message 

returned an error code to PCFP indicating that it could not successfully 

complete its operation. 

Symbolic Name: fp_err_after_src_swap 

2266 The caller subroutine called by PCFP to process the destination file swap 

message returned an error code to PCFP indicating that it could not 


Symbolic Name: fp_err_after_dest_swap 

2301 The source tape file could not be read because it has inconsistent block 

sizes. The number of words transferred () is not a multiple of 

the tape block size. 

Symbolic Name: fp_err_bad_blocking 

This error frequently indicates invalid or corrupted data on the tape file. Note 

that the tape block size for FURPUR format tape files (FORMAT = FURPUR) 

should be a multiple of 1,794 words (2 header words + 1,792 data words). 

2302 The source tape file could not be read because it has a badly formed track 

header. 

Symbolic Name: fp_err_bad_track_header 

This error frequently indicates invalid or corrupted data on the tape file. 

2303 The status returned on the read of the source tape file indicates that one or 

more words from a tape block were discarded because they did not fit in the 

provided buffer space. 

Symbolic Name: fp_err_data_truncated 

PCFP always provides enough buffer space to contain the expected size of 

the entire tape block for the format of the tape file being processed. This 

error indicates that a block larger than the expected size was read. This 

abnormal condition indicates invalid or corrupted data on the tape file or a 

hardware or microcode error. 

2304 The function could not be completed because the tape file with index 

does not allow backward movement. 

Symbolic Name: fp_err_no_backward_alwd 

2340 Unexpected status 11 with I/O status was returned by ER 

TLBL$ against the tape file with index . 

Symbolic Name: fp_err_bad_tlbl_io 

2341 Unexpected status was returned by ER TLBL$ against the tape 

file with index . 

Symbolic Name: fp_err_bad_tlbl 

A–32 7830 9796–013


2342 Unexpected status was returned by ER TINTL$ against the 

tape file with index . 

Symbolic Name: fp_err_bad_tintl 

2343 Unexpected status was returned by ER TSWAP$ against the 

tape file with index . 

Symbolic Name: fp_err_bad_tswap 

2344 The function cannot be performed because of a previous Locate Block 

(LBLK$) I/O function against the tape file with index . 

Symbolic Name: fp_err_locate_block 

Tape files positioned with Locate Block are write inhibited, so the functions 

CLOSE_SAF, COPY_RAF_SAF and COPY_SAF_SAF (with the positioned tape 

as the destination file) are not allowed. 

2345 The requested tape positioning cannot be performed because fast tape 

access is not supported for this tape equipment type. 

Symbolic Name: fp_err_no_fast_tape_access 

2346 The requested tape positioning cannot be performed because your run does 

not have the privileges that are required for a Locate Block (LBLK$) I/O 

function. 

Symbolic Name: fp_err_no_locate_block_priv 

For systems with Fundamental Security (SENTRY_CONTROL FALSE), the 

caller must be running under the overhead account or the security officer 

account or must have SYS$*DLOC$ assigned to the run with the correct read 

and write keys. For systems with Security Option 1, 2, or 3 

(SENTRY_CONTROL TRUE), the special privileges 

bypass_tape_hdr1_read_checks (SSBHDR1RDCHK) and bypass_object_reuse 

(SSBYOBJREUSE) are required. 

A.2.5. Execution Errors Other than I/O Errors—Random-Access 

Files 

2501 The maximum size of the destination file is too small. 

Symbolic Name: fp_err_file_too_small 

The function was terminated when the destination file was filled to its 

maximum size. 

7830 9796–013 A–33


2502 The file with index is not initially empty and the function packet 

indicates that it must be empty. 

Symbolic Name: fp_err_dest_not_empty 

The COPY_OMN_ELT_RAF, COPY_RAF_RAF, and COPY_SAF_RAF functions 

return this error message when Prevent_Overcopy is TRUE and the 

destination file is not empty. To complete the function, erase the destination 

file with the ERS_RAF function or set Prevent_Overcopy to FALSE. 

The COPY_SYM_ELT_RAF function returns this error message when Action is 

must_be_empty (1) and the destination file is not empty. To complete the 

function, erase the destination file with the ERS_RAF function or set Action to 

overcopy (0). 

The CHG_FILE function returns this error message when Init_Program_File is 

other than none (0) and the file is already a program file. To complete the 

function, erase the file with the ERS_RAF function or set Init_Program_File to 

none (0). 

The COPY_ELT, COPY_RAF_OMN_ELT, and COPY_RAF_SYM_ELT functions 

return this error message when Init_Dest_File is other than none (0) and the 

destination file is already a program file. To complete the function erase the 

destination file with the ERS_RAF function or set Init_Dest_File to none (0). 

2503 The file or element being copied contains a hole (unallocated area) within the 

text. 

Symbolic Name: fp_err_hole_in_file 

Elements or files that are to become elements must not contain a hole 

(unallocated area) within the text. 

2504 File sharing is down. The use of shared files is not currently allowed. 

Symbolic Name: fp_err_file_sharing_down 

2511 System Error: Unexpected status was returned by the DREAD$ 

function of ER MSCON$ while attempting to retrieve the directory items 

associated with the file with index . 

Symbolic Name: fp_err_bad_dread 

2512 System Error: Unexpected status was returned by the DIRID$ 

function of ER MSCON$ while attempting to retrieve the directory-id names 

for the system. 

Symbolic Name: fp_err_bad_dirid 

2513 System Error: Unexpected status was returned by the EXIST$ 

function of ER MSCON$ while attempting to retrieve the directory items 

associated with the file submitted to PCFP. 

Symbolic Name: fp_err_bad_exist 

A–34 7830 9796–013


2514 System Error: Unexpected status was returned by the MULTI$ 

function of ER MSCON$ while attempting to change the attributes associated 

with the file submitted to PCFP. 

Symbolic Name: fp_err_bad_multi 

2515 System Error: Unexpected Status was returned by the DCYC$ 

function of ER MSCON$ while attempting to change the F-cycle range of the 

file submitted to PCFP. 

Symbolic Name: fp_err_bad_dcyc 

2516 System Error: Unexpected Status was returned by the DKEY$ 

function of ER MSCON$ while attempting to change the read/write keys of 

the file submitted to PCFP. 

Symbolic Name: fp_err_bad_dkey 

2517 System Error: Unexpected status was returned by the DBITS$ 

function of ER MSCON$ while attempting to change the security attributes 

associated with the file submitted to PCFP. 

Symbolic Name: fp_err_bad_dbits 

2518 System Error: Unexpected status was returned by the 

NAMCHG$ function of ER MSCON$ while attempting to change the name of 


Symbolic Name: fp_err_bad_namchg 

2519 System Error: Unexpected I/O error status was returned by the 

NAMCHG$ function of ER MSCON$ while attempting to change the name of 


Symbolic Name: fp_err_bad_namchg_io 

7830 9796–013 A–35


2520 Device Area Descriptor (DAD) table sector number is too large 

for the DREAD$ function of ER MSCON$. 

Symbolic Name: fp_err_dad_sector_too_large 

COPY_RAF_RAF and COPY_RAF_SAF read DAD tables for cataloged mass 

storage source files to improve the efficiency of copy operations. The source 

file has too many DAD sectors and cannot be completely copied to the 

destination file. The function packet item Amount_Copied contains the 

number of words that were correctly copied when this error was detected. 

2521 System Error: Unexpected Status was returned by ERSUMOD$ 

while attempting to change the security attributes associated with the file 

submitted to PCFP. 

Symbolic Name: fp_err_bad_sumod 

2522 The value specified for Clearance_Level in the function packet does not lie in 

the file's clearance level range. 

Symbolic Name: fp_err_cl_level_out_of_range 

2523 An Access Control Record (ACR) whose name matches the value specified for 

ACR_Name in the function packet and which is owned by your user-id does 

not exist. 

Symbolic Name: fp_err_unknown_acr_name 

2524 Attributes of the new File_Owner_User_Id and the file are not compatible. 

Symbolic Name: fp_err_owner_file_not_compat 

2525 An ACR cannot be attached to the file because it is shared and unowned. 

Symbolic Name: fp_err_bad_shared_acr 

2526 The owner of the ACR does not match the owner of the file. 

Symbolic Name: fp_err_acr_file_owner_mismatch 

The owner of the ACR must match the owner of the file in order for the ACR 

to be attached to the file. 

2527 A user id which matches the value specified for File_Owner_User_Id in the 

function packet does not exist. 

Symbolic Name: fp_err_unknown_file_owner 

2528 You cannot change the security attributes of a file you do not own. 

Symbolic Name: fp_err_not_file_owner 

Only the owner of a file (or a user given special privileges by the security 

administrator) can change the owner, privacy, ACR, or clearance level of that 

file. 

A–36 7830 9796–013

2531 System Error: An unexpected status was returned by 

ERCONFIG$ while attempting to perform the requested function. 

Symbolic Name: fp_err_bad_Config 


A.2.6. Execution Errors Other than I/O Errors—Program Files 

2601 The file with index is not a program file and the called function 

requires a program file. 

Symbolic Name: fp_err_not_pf 

2602 The file with index is an empty file and the called function 

requires a non-empty program file. 

Symbolic Name: fp_err_empty_file 

2603 The function could not be completed because the program file table of 

contents for table does not have enough open entries. 

Symbolic Name: fp_err_toc_space_too_small 

Completion of the function requires more table entries than the program file 

table of contents can contain. 

Table 1 is the element table. 

Table 2 is the MASM procedure table. 

Table 3 is the COBOL procedure table. 

Table 4 is the FORTRAN/PLUS procedure table. 

Table 5 is the relocatable entry point table. 

The maximum number of entries for each table depends on the table type and 

whether this is a standard program file or a large program file. You may be 

able to complete the function by removing deleted elements from the 

program file with the PACK_PF function. 

2604 The function did not create an element because the destination file already 

contains an element with the same name, version, and type. The sequence 

of the duplicate element is . 

Symbolic Name: fp_err_elt_conflict 

2605 The operation could not be performed because the program file with index 

is missing all or part of its table of contents. 

Symbolic Name: fp_err_pf_toc_truncated 

2606 The operation could not be performed because the program file with index 

is missing all or part of its element text. 

Symbolic Name: fp_err_elt_text_truncated 

2607 Text size of words exceed the maximum of 7,340,004 words 

allowed for a PF or LPF program file element. 

Symbolic Name: fp_err_elt_text_too_large 

7830 9796–013 A–37


This error is returned when attempting to create an element in a PF or LPF. 

The maximum element text size for a PF or LPF program file element is 

0777777 sectors (18-bit octal value) or 262,143 sectors (decimal value). These 

values can be converted to a decimal value of 7,340,004 words. 

2608 Text size of words exceeds the maximum allowed for an LEPF 

program file element. 

Symbolic Name: fp_err_lepf_elt_text_too_large 

This error is returned when attempting to create an element in an LEPF. The 

maximum element text size for an LEPF program file element is dependent on 

the element type. In all cases, the size must be less than the maximum file 

size (262,143 positions or 16,777,152 tracks or 1,073,737,728 sectors or 

30,064,656,384 words) minus the size of the standard program file table of 

contents (28 tracks or 1,792 sectors or 50,176 words) or the size of the large 

program file table of contents (629 tracks or 40,256 sectors or 1,127,168 

words). 

2609 The LEPF program file element with sequence number has an 

illegal element text length granularity value. 

Symbolic Name: fp_err_bad_granularity 

This error is returned when reading an LEPF element. For the indicated 

element, the 2-bit element text length granularity field (element table item 

word 3, bits 1 and 2) has an illegal value of 3. 

2610 The LEPF program file element with sequence number has a 

text size that exceeds the maximum. 

Symbolic Name: fp_err_bad_elt_text_length 

This error is returned when reading an LEPF element. PCFP converts the 

element text length, which is in sectors, tracks, or positions as indicated by 

the element text length granularity, to a text size value that is in number of 

words. For the indicated element, the text size exceeded the largest positive 

value that can be stored in a 36-bit word. The largest legal value is 

0377777777777 or 34,359,738,367 words. Note that this value is actually 

somewhat larger than the 30,064,606,208 words that are currently possible 

for the largest possible element in the largest possible standard program file 

or the 30,063,479,040 words that are currently possible for the largest 

possible element in the largest possible large program file. 

2611 Symbolic procedure, relocatable and absolute elements cannot be copied to 

an LEPF. 

Symbolic Name: fp_err_bad_lepf_elt_type 

Symbolic procedure elements (symbolic subtypes 29, 64, 65, and 66), 

relocatable elements, or absolute elements cannot be copied to an LEPF 


A–38 7830 9796–013


2612 The element with the sequence number specified is not correctly linked by 

element name, element version or element type. 

Symbolic Name: fp_err_elt_link_type 

The element sequence number links contained in the program file pointer 

table and the element entries are incorrect or inconsistent. The program file 

table of contents should be rebuilt with the PCFP PACK_PF function to correct 

the links. 

2650 The Basic Service Package (BSP) detected a program file format error with the 

error code for the file with index . 

Symbolic Name: fp_err_bsp_pf_format_err 

The Basic Service Package routine called by PCFP detected an error in the 

format of the program file and was unable to continue. Refer to the SYSLIB 

Programming Reference Manual for the interpretation of the displayed error 

code. 

2651 The program file with index does not have a recognizable table 

of contents. 

Symbolic Name: fp_err_bad_pf_toc 

Program-file functions cannot be used on this file. 

2652 The program file contains duplicate elements (same name, version, and type). 

The sequence number of the second element of the duplicate pair is 

. 

Symbolic Name: fp_err_duplicate_elt 

A valid program file does not contain duplicate elements. This file cannot be 

packed until you delete the duplicate elements. 

2653 The table of contents of the program file indicates that the text of two 

elements in the file overlap. The sequence number of one of these elements 

is . 

Symbolic Name: fp_err_overlapped_elts 

A valid program file does not contain overlapping elements. This file cannot 

be packed as doing so might destroy the text of one or more elements in the 

file. 

2654 An unexpected error was returned by the Basic Service 

Package (BSP). 

Symbolic Name: fp_err_bsp_err 

A Basic Service Package routine is called by PCFP for program file 

manipulations. This error may indicate corruption of the data in the program 

file. Refer to the SYSLIB Programming Reference Manual for its 

interpretation. 

7830 9796–013 A–39


2655 An unexpected I/O error was returned by the Basic Service 

Package (BSP). 

Symbolic Name: fp_err_bsp_io_err 

A Basic Service Package routine called by PCFP for program file manipulations 

detected an I/O error. This error may indicate corruption of the data in the 

program file. 

2656 System Error: An undefined error code was returned by the 

Basic Service Package (BSP). 

Symbolic Name: fp_err_bsp_illegal_err 

A Basic Service Package routine called by PCFP for certain program file 

manipulations returned an undefined or illegal error code. 

2657 PCFP Internal Error: 

Symbolic Name: fp_err_bsp_caller_err 

The Basic Service Package detected an error in the calling sequence, buffer 

size, or buffer contents supplied by PCFP. This indicates a PCFP logic error. 

Refer to the SYSLIB Programming Reference Manual for the interpretation of 

the displayed error code. 


Symbolic Name: fp_err_bsp_no_find 

A logic problem was detected within PCFP, concerned with handling of a 

Basic Service Package (BSP) status. 

2659 System Error: Installation of a more recent SYSLIB level is required. The 

referenced SYSLIB Basic Service Package (BSP) does not support all of the 

functionality required by PCFP. 

Symbolic Name: fp_err_bad_syslib_level 

Information returned by the SYSLIB BSP$ Read File Table Index (RFTI$$) 

function indicates that the level of SYSLIB referenced does not support the 

functionality required by the PCFP program file functions. Refer to the 

ClearPath IX and 2200 Series Software Planning and Migration Overview 

release level 7.0 for your installed ClearPath or 2200 system release level to 

determine the level of SYSLIB that corresponds to this level of PCFP. 

2661 The element with the name and version you specified, and the type required 

by the function, does not exist in the program file. 

Symbolic Name: fp_err_nonexistent_elt 

2662 The symbolic cycle specified does not exist in the element specified. 

Symbolic Name: fp_err_nonexistent_cycle 

A–40 7830 9796–013


2663 The sequence number specified does not exist in the program file. The 

largest sequence number in the file is . 

Symbolic Name: fp_err_nonexistent_seq_num 

2672 System Error: The Run-Time library routines used by the Linking System have 

not been installed. 

Symbolic Name: fp_err_ls_missing_bank 

2673 System Error: A bank containing the Linking System (LS) routines called by 

PCFP to either prep or retrieve object module entry points has not been 

installed. 

Symbolic Name: fp_err_no_ls_bank 

2674 Unexpected status was returned by a Linking System (LS) 

routine which was called by PCFP to operate on a program file. 

Symbolic Name: fp_err_ls_err 

This error might indicate corruption of the data in the program file. 

2675 Unexpected I/O error was returned by a Linking System(LS) 

routine called by PCFP to operate on a program file. 

Symbolic Name: fp_err_ls_io_err 

This error often indicates that the file is not large enough to contain the object 

module entry point table. You should expand the size of the file you want 

prepped. In some cases, this error might indicate corruption of the data in the 

program file. 

2676 System Error: An undefined error status was returned by a 

Linking System (LS) routine which was called by PCFP to operate on a 

program file. 

Symbolic Name: fp_err_ls_illegal_err 

2677 System Error: Linking System (LS) Internal Error: 

Symbolic Name: fp_err_ls_internal_err 

A Linking System (LS) routine called by PCFP to operate on the program file 

returned an internal error type. 

2678 Unexpected I/O error was returned by a Linking System (LS) 

routine called by PCFP to operate on a program file while it attempted to write 

to a temporary file. 

Symbolic Name: fp_err_ls_io_temp_err 

This error occurred while the Linking System was collecting information about 

the entry points in the program file. 

2701 The SDF file or element being operated on does not contain legal SDF text. 

The text contains no Label Control Record. 

Symbolic Name: fp_err_bad_sdf_label_record 

7830 9796–013 A–41


2702 The SDF file or element being operated on contains a type of SDF text that 

the PCFP function cannot handle. 

Symbolic Name: fp_err_bad_sdf_type 

The operation requested requires a symbolic element containing text with 

symbolic element cycles. This implies that the text type of the element must 

be general-symbolic (’S’). The element you attempted to operate on contains 

a different type of symbolic text. 

2706 PCFP could not copy the SDF file or symbolic element because it contains no 

SDF end-of-text control record. 

Symbolic Name: fp_err_no_sdf_eof 

2721 The relocatable element with sequence number contains a 

relocatable preamble with an invalid index and/or count for the element's 

relocatable entry point table. 

Symbolic Name: fp_err_bad_rel_preamble 

To create a program file Relocatable Element Entry Point Table (REEPT), the 

PREP_PF function must be able to correctly read the entry point tables for 

each relocatable element that is not deleted. The entry point table could not 

be read for the element indicated in the message. The entry point table index 

and the entry point table item count indicate that some or all of the entry point 

table is beyond the end of the relocatable preamble. This error could indicate 

that the relocatable text for this element has been corrupted. This element 

must be deleted with the PCFP DELETE_ELT function or the FURPUR 

@DELETE,R command before the REEPT can be created with the PCFP 

PREP_PF function or the FURPUR @PACK,P or @PREP commands. 

Note that there may be additional relocatable elements beyond the one 

indicated that also have invalid entry point tables. 

A.2.7. Errors Associated with Assigning and Freeing Files 

3001 The file with index could not be assigned and the error 

returned by the attempted assign was . 

Symbolic Name: fp_err_cant_asg 

3002 The file with index could not be exclusively assigned and the 

error returned by the attempted exclusive assign was . 

Symbolic Name: fp_err_cant_asg_x 

3003 The error was returned while trying to attach an internal 

name (@USE) to the file with index . 

Symbolic Name: fp_err_cant_attach_use 

3004 The file with index does not exist. 

Symbolic Name: fp_err_file_not_found 

The file is neither cataloged nor is it assigned to your run. 

A–42 7830 9796–013


3005 The file with index could not be assigned with the AE 

options, because it is already assigned with the AY options. 

Symbolic Name: fp_err_file_state_wrong 

PCFP must assign the file with the AE options, but it was previously 

assigned with the AY options. Since these options are mutually exclusive, 

you must free the file before the requested function can be performed on 

the file. 

3006 The file with index cannot be assigned in the manner 

required by the function. 

Symbolic Name: fp_err_file_rw_inhibited 

The file was previously assigned with the AE or AY options, which prevents 

the file from being read from or written to. You must free the file before 

the requested function can be performed on the file. 

3010 The file with index could not be freed; the error returned by 

the attempted free was . 

Symbolic Name: fp_err_cant_free 

The file was assigned automatically by PCFP. The error occurred when 

PCFP attempted to free the file. 

3011 The file with index could not be deleted; the error returned 

by the attempted delete was . 

Symbolic Name: fp_err_cant_free_d 

The file was assigned automatically by PCFP. The error occurred when 

PCFP attempted to delete the file as required by the function. 

3012 The file could not be deleted, because it was on a symbiont queue. 

Symbolic Name: fp_err_file_on_sym_q 

The file must be removed from the symbiont queue before it can be 

deleted. 

3021 Error message number was returned while trying to assign 

the file SYS$DLOC$. 

Symbolic Name: fp_err_cant_asg_dloc 

PCFP attempted to assign this file automatically, since its assignment is 

required to perform the requested function. 

3031 Error message number was returned while trying to assign a 

temporary file that PCFP needs to complete the processing of the 

requested function. 

Symbolic Name: fp_err_cant_asg_temp 

3032 Error message number was returned while trying to free a 

temporary file that PCFP used to complete the processing of the requested 

function. 

7830 9796–013 A–43


Symbolic Name: fp_err_cant_free_temp 

3033 The file submitted to the PACK_LPF function is not assigned and it is 

required that the file be assigned. 

Symbolic Name: fp_err_file_not_asgd 

3051 The file with index has an unknown equipment code 

, which is not handled by PCFP. 

Symbolic Name: fp_err_unknown_equip_code 

Although the equipment code is printed in octal, it should be interpreted as 

Fieldata. 

A–44 7830 9796–013

A.2.8. Errors Associated with the PACK_PF Function 


The errors listed in this subsection can occur when using the copy method of the 

PACK_PF function. See 8.4 for additional information on the PACK_PF copy method. 

These error codes are returned when a PCFP function called by the copy method 

encounters an error. 

The errors listed in this subsection have an associated Sub_Error_Code and should be 

handled as described at the beginning of this appendix. For each error message, the 

“Error code = , auxiliary error code = , error file index = 

” is displayed only if an ELMS explanation level of 2 or greater is 

requested. 

3502 During a program file pack, the copy of the program file elements to the 

temporary intermediate file resulted in the following error: 

Error code = , auxiliary error code = , error file 

index = . 

Symbolic Name: fp_err_cant_copy_to_temp 

The COPY_ELT function was called by the PACK_PF function to copy the 

requested nondeleted elements and procedures from a program file that is 

being packed to a temporary intermediate file. In the process, it encountered 

and returned the error code and auxiliary error code shown in the error 

message and contained in the function packet Sub_Error_Code and 

Aux_Error_Code items. 

3503 During a program file pack, the copy of the temporary intermediate file back to 

the program file resulted in the following error: 


index = . 

Symbolic Name: fp_err_cant_copy_from_temp 

The COPY_RAF_RAF function was called by the PACK_PF function to copy the 

contents of the temporary intermediate file back to the program file being 

packed. In the process, it encountered and returned the error code and 

auxiliary error code shown in the error message and contained in the function 

packet Sub_Error_Code and Aux_Error_Code items. 

3504 During a program file pack, the clearing of the temporary intermediate file 

resulted in the following error: 


index = . 

Symbolic Name: fp_err_cant_clear_temp 

The ERS_RAF function was called by the PACK_PF function to zero-out the 

temporary intermediate file after the contents of that file had been copied back 

to the program file being packed. In the process, it encountered and returned 

the error code and auxiliary error code shown in the error message and 

contained in the function packet Sub_Error_Code and Aux_Error_Code items. 

3506 During a program file pack, the prepping of the program file resulted in the 

following error: 


7830 9796–013 A–45


index = . 

Symbolic Name: fp_err_cant_prep 

The PREP_PF function was called by the PACK_PF function to prep a program 

file that was just packed. In the process, it encountered and returned the error 

code and auxiliary error code shown in the error message and contained in the 

function packet Sub_Error_Code and Aux_Error_Code items. 

A–46 7830 9796–013

Appendix B 

Summary of FURPUR Commands 

This appendix is not meant to be used as a FURPUR reference. The ECL and FURPUR 

Reference Manual is written for that purpose and contains the complete description of 

FURPUR commands and options. 

This appendix is meant to summarize all available FURPUR commands and to indicate 

the analogous PCFP function or functions, when applicable. In Table B–1 the FURPUR 

commands are presented alphabetically in the first column, generally in the same order 

that they appear in the ECL and FURPUR Reference Manual. The second column 

provides a brief description of the command; where applicable it also refers to notes that 

follow Table B–1. The third column provides the analogous PCFP function name or not 

available if there is no analogous PCFP function. The fourth column provides additional 

information on PCFP function packet fields that relate to the FURPUR command. 

The following abbreviations are used with FURPUR commands shown in the first column 

of Table B–1. 

file 

ms 

tape 

pf 

elt 

The name of a file. It is used as an abbreviation for the fully qualified file name. 

The name of a mass storage file; used when it is necessary to differentiate this file 

from a tape file. 

The name of a tape file; used when necessary to differentiate this file from a mass 

storage file. 

The name of a mass storage file that has been formatted as a standard program file 

or as a large program file. 

The name of a program file element. It is used as an abbreviation for the fully 

qualified file name and element name. 

7830 9796–013 B–1


SDF 

The name of mass storage file or a tape file that has been formatted as a system 

data format (SDF) file. 

Table B–1. Summary of FURPUR Commands 

FURPUR Command Description PCFP Function Packet Fields 

@CHG 

file/r1/w1.,file/r2/w2 

Change file read key, 

write key 

@CHG,F file.,spec Change file caching 

specifications 

CHG_FILE_KEYS READ_KEY=r2 

WRITE_KEY=w2 

Not available 

@CHG,N file1.,file2. Change file name CHG_FILE_NAME 

@CHG,P file. Set public mode CHG_FILE_SEC PRIVACY=PUBLIC 

@CHG,Q file. Set private mode CHG_FILE_SEC PRIVACY=PUBLIC 

@CHG,K file.,acr Set semiprivate mode CHG_FILE_SEC PRIVACY= 

SEMIPRIVATE 

ACR_NAME=acr 

@CHG,T file. 

@CHG,E file. 

Initialize large program 

file or large element 

program file 

@CHG,V file. Set read-only, clear 

write-only mode 

@CHG,W file. Set write-only, clear 

read-only modes 

@CHG,Z file. Clear read-only and 

write-only modes 

@CHG,AORS 

elt1,elt2 

@CLOSE 

tape1.[,tape2.,...] 

Change element, 

version names; see 

notes 1, 2, 3, and 4 

Close tapes and rewind; 

see notes 5 and 8 

@COPIN tape.,pf. Copy from element 

format tape to program 

file 

@COPOUT pf.,tape. Copy from program file 

to element format tape 

CHG_FILE INIT_PROGRAM_ 

FILE 

CHG_FILE READ_ONLY= 

SET_ON 

WRITE_ONLY= 

SET_OFF 


SET_OFF 

WRITE_ONLY= 

SET_ON 


SET_OFF 

WRITE_ONLY= 

SET_OFF 

CHG_ELT 

CLOSE_SAF 

MOVE_SAF 

Not available 

Not available 

TYPE_OF_MOVE= 

TO_SAF_START 

CURRENT_VOL_ 

ONLY=FALSE 

B–2 7830 9796–013




Copy mass storage file to mass storage file 

@COPY ms.,ms. Copy mass storage file 

to mass storage file 

@COPY,AORS 

elt1,elt2 

@COPY,P pf1.,pf2. 

@COPY,F 

SDF1.,SDF2. 

Copy elements; see 

notes 1, 2, 3, 4, and 6 

Copy SDF file to SDF 

file 

@COPY,I SDF.,elt Copy SDF file to 

symbolic element 

@COPY,I elt,SDF. Copy symbolic element 

to SDF file 

@COPY,IO ms.,elt Copy mass storage file 

to omnibus element 

@COPY,IO elt,ms. Copy omnibus element 


@COPY ms.,tape. Unformatted copy of 

mass storage file to 

tape file 

COPY_RAF_RAF 

COPY_ELT 

Not available 

COPY_RAF_SYM_ 

ELT 

COPY_SYM_ELT_ 

RAF 

COPY_RAF_OMN_ 

ELT 

COPY_OMN_ELT_ 

RAF 

Copy mass storage file to tape file 

@COPY,B ms.,tape. Copy FORTRAN mass 

storage data file to tape 

file 

@COPY,F SDF.,tape. Copy SDF mass 

storage file to tape file 

@COPY,G ms.,tape. Formatted copy of 


tape file 

@COPY,I elt,tape. Copy symbolic element 

to SDF tape file 

@COPY,IO elt,tape. Copy omnibus element 

to tape file 

@COPY,V ms.,tape. Copy variable block size 


tape file 

@COPY tape.,ms. Unformatted copy of 

tape file to mass 

storage file 

Not available 

Not available 

Not available 

COPY_RAF_SAF 

Not available 

Not available 

Not available 

Copy tape file to mass storage file 

Not available 

7830 9796–013 B–3




@COPY,B tape.,ms. Copy FORTRAN tape 

file to mass storage 

data file 

@COPY,F tape.,SDF Copy SDF tape file to 

mass storage file 

@COPY,G tape.,ms. Formatted copy of tape 

file to mass storage file 

@COPY,I tape.,elt Copy SDF tape file to 


@COPY,IO tape.,elt Copy tape file to 

omnibus element 

@COPY,N tape.,ms. Copy tape file with 

abnormal frame count 


@COPY,V tape.,ms. Copy variable block size 

tape file to mass 

storage file 

@COPY 

tape.,tape.[,#files] 

Not available 

Not available 

COPY_SAF_RAF 

Not available 

Not available 

Not available 

Not available 

Copy tape file to tape file 

Unformatted copy of 

tape files to tape files; 

see note 7 

@COPY,F SDF.,SDF Copy SDF tape file to 

SDF tape file 

@COPY,M 

tape.,tape.[#files] 

Unformatted copy of 

tape files to tape files 

with hardware EOF 

mark separating files; 

see note 7 

@COPY,N tape.,tape. Copy tape file with 

abnormal frame count 

to tape file 

@COPY,T tape.,tape. Copy 8-bit labeled tape 

file to tape file 

@CYCLE file. Display F-cycle 

information 

@CYCLE file.,#cycles Set maximum F-cycle 

range 

Not available 

Not available 

Not available 

Not available 

Not available 

ACQ_FILE_INFO INFO_DETAIL= 

LONG or 

COMPLETE 

CHG_FILE_CYC MAX_F_CYCLES= 

#cycles 

B–4 7830 9796–013




@CYCLE elt,#cycles Set maximum element 

cycle range 

@DELETE 

file1.,[,file2.,...] 

@DELETE,AORS 

elt1[,elt2,...] 

Delete files; see notes 8 

and 15 

Delete elements; see 

notes 1, 2, 3, and 8 

@DELETE,UAORS Undelete elements; see 

notes 1, 2, 3, and 8 

@ENABLE 

file1.[,file2.,...] 

Clear disable indicators 

for files; see note 8 

@ERS file1.[,file2.,...] Erase files; see notes 8 

and 9 

@FIND tape. Locate an element on 

an element format tape 

@MARK tape. Write hardware EOF 

mark on a tape 

CHG_ELT NEW_CYCLE_ 

LIMIT=#cycles 

DELETE_FILE 

DELETE_ELT 

UNDELETE_ELT 

CHG_FILE DIRECTORY_ 

DISABLE= 

SET_OFF 

WRITE_DISABLE= 

SET_OFF 

BACKUP_ 

DISABLE= 

SET_OFF 

CACHE_ 

DISABLE= 

SET_OFF 

ERASE_RAF STORAGE_TO_ 

RELEASE=ALL_ 

BUT_INITIAL_ 

RESERVE 

ZERO_FIRST_ 

TRACK_ONLY_IF_ 

WRITTEN=TRUE 

Not available 

Not available 

@MOVE tape.[,#files] Move tape forward MOVE_SAF TYPE_OF_MOVE= 

FORWARD 

MOVE_NUM= 

#files 

@MOVE,B 

tape.[,#files] 

Move tape backward MOVE_SAF TYPE_OF_MOVE= 

BACKWARD 

MOVE_NUM= 

#files 

POSITION_AT_ 

END_OF_LOG_ 

FILE=TRUE 

CURRENT_VOL_ 

ONLY=TRUE 

7830 9796–013 B–5




@PACK pf1.[,pf2.,...] Remove deleted 

elements; see notes 8, 

9, 10, and 11 

@PACK,P 

pf1.[,pf2.,...] 

Remove deleted 

elements and create 

entry point tables; see 

notes 8, 9, 10, and 11 

@PCH elt Punch symbolic 

element 

@PREP pf1.[,pf2.,...] Create entry point 

tables; see notes 8 and 

12 

@PRT Print master file 

directory (MFD) 

@PRT,D 

pack1[,pack2,...] 

@PRT,F 

file1.[,file2.,...] 

Print files on named 

removable packs 

Print information for 

files; see notes 8 and 

13 

@PRT,IL Print file information 

about files assigned to 

the run; see note 14 

@PRT,N Print files by account 

number 

PACK_PF 

PACK_PF 

PREP_PF 

Not available 

EP_TYPE=BOTH 

PREP_PF EP_TYPE=BOTH 

Not available 

Not available 

ACQ_FILE_INFO INFO_DETAIL= 

LONG or 

COMPLETE 

ACQ_FILE_LIST INFO_DETAIL= 

LONG or 

COMPLETE 

SEARCH_SET= 

KNOWN_TO_ 

RUN 

Not available 

@PRT,P Print files by project-id Not available 

@PRT,S elt1[,elt2,...] Print symbolic element 

contents 

@PRT,T pf1.[,pf2.,...] Print element 

information; see notes 

1, 2, 3, 8, and 14 

@PRT,U 

pack1[,pack2,...] 

@REWIND 

tape1.[,tape2.,...] 

Print usage of named 

removable packs 

Rewind tapes to load 

point; see notes 5 and 8 

Not available 

ACQ_ELT_INFO 

ACQ_REL_EP_ 

INFO 

ACQ_OM_EP_ 

INFO 

ACQ_PROC_INFO 

Not available 

MOVE_SAF TYPE_OF_MOVE= 

TO_SAF_START 

B–6 7830 9796–013

Notes: 

1. Specify FURPUR options in a PCFP function packet as follows: 

• Specify the A option by setting ABS_TYPE = TRUE. 

• Specify the O option by setting OMN_TYPE = TRUE. 

• Specify the R option by setting REL_TYPE = TRUE. 

• Specify the S option by setting SYM_TYPE = TRUE. 


Setting all four PCFP function packet conditions to either TRUE or FALSE can specify 

all four FURPUR options. 

2. The FURPUR Y option is used together with the A option and the third FURPUR 

parameter to specify absolute element subtype. The PCFP function packet provides 

the ABS_SUBTYPE condition array to provide this capability. 

• Specify the FURPUR third parameter value of ABS in a PCFP function packet by 

setting ABS_SUBTYPE(0) = TRUE. 

• Specify OM by setting ABS_SUBTYPE(1) = TRUE. 

• Specify SD by setting ABS_SUBTYPE(2) = TRUE. 

• Specify ZM by setting ABS_SUBTYPE(3) = TRUE. 

• Specify BOM by setting ABS_SUBTYPE(17) = TRUE. 

3. The format of the element name, the presence of the FURPUR V option and the * 

version name masking character together are used to select program file elements 

from a source file. Analogous element selection capabilities are provided in a PCFP 

function packet using different formats of the ELT_NAME and ELT_VERSION fields 

and the ? PCFP wild-card character. Note that the PCFP function packet must have 

QUESTION_MARK_MATCHES_SPACE = TRUE for the ? wild-card character to 

operate the same as the FURPUR * version name mask character. 

4. The FURPUR X option is used together with the format of the element name to 

determine the element name and version name to be used for a destination file. 

Analogous element naming capabilities are provided in a PCFP function packet using 

different formats of the NEW_ELT_NAME (or DEST_ELT_NAME) and 

NEW_ELT_VERSION (or DEST_ELT_VERSION) fields. 

5. Specify the FURPUR I option in the PCFP MOVE_SAF function packet by setting 

INTERLOCK = TRUE. 

6. Specify the FURPUR L option in the PCFP COPY_ELT function packet by setting 

COPY_CURRENT_CYCLE = TRUE. 

7. The only tape to tape copy supported by PCFP is the COPY_SAF_SAF function, 

which can be used to copy a single file created by the FURPUR @COPY,G ms.,tape. 

command or by the PCFP COPY_RAF_SAF function to a destination tape file. 

8. The FURPUR command can process up to 63 files on one command line; the PCFP 

function can process only one file on each PCFP function call. 

7830 9796–013 B–7


9. Specify FURPUR options in a PCFP function packet as follows: 

• Specify the FURPUR I option by setting STORAGE_TO_RELEASE = 

ALL_STORAGE. 

• Specify the FURPUR N option by setting STORAGE_TO_RELEASE = NONE. 

• Specify the FURPUR Z option by setting ZERO_RELEASED_STORAGE = TRUE. 

• Specify the FURPUR G option (@ERS only) by setting 

ZERO_RETAINED_STORAGE = TRUE. 

10. The FURPUR D, L and M options are not available on the PCFP PACK_PF function. 

11. The FURPUR A, O, R, S and Y options are not directly available on the PCFP 

PACK_PF function. The affect of these options can be achieved using PCFP by 

performing a DELETE_ELT function with the proper settings for ABS_TYPE, 

OMN_TYPE, REL_TYPE, SYM_TYPE, and the ABS_SUBTYPE array, followed by a 

PACK_PF function. 

12. The FURPUR F option can be specified in the PCFP PREP_PF function packet by 

setting OVERWRITE_OLD_EP_TABLE = TRUE. The FURPUR L option is not 

available on the PCFP PREP_PF function. 

13. File caching information displayed by the FURPUR @PRT function is not available 

with the PCFP ACQ_FILE_INFO and ACQ_FILE_LIST functions. 

14. The FURPUR B option is not available in PCFP. 

15. The FURPUR N option is not available in PCFP. 

B–8 7830 9796–013

Appendix C 

PACK_PF Operation and Performance 

Many factors affect the performance of the PACK_PF function. The size of the file to be 

packed is the primary factor. Small files can be quickly packed with very little attention 

to pack method or to optimizing work area requirements. Large files take a long time to 

pack, but careful selection of the pack method and options and attention to work area 

requirements can yield big performance improvements. The two pack methods are 

described in C.1 and C.2 and their performance is compared in C.3. 

C.1. Standard Method Performance 

The standard method uses a two-step process to pack a file (see 8.4). The first step 

involves rebuilding and rewriting all of the program file tables. For a standard program 

file, this is a maximum of 21 tracks for all tables. In almost every case, this is much 

smaller than the element text to be copied in the second step. Even for a large program 

file, where the element table is a maximum of 146 tracks for 26,146 elements or where 

all maximum size tables total 584 tracks, the program file tables are usually much smaller 

than the element text. This means that the performance of the first step is almost 

always a very small component of the total performance of the PACK_PF function, 

particularly as the number of undeleted elements and the size of the element text 

increases. 

During the second step of the standard method, the text of remaining elements is 

copied, if necessary, so that the text of each element immediately follows the text of the 

previous element. If the element text is copied, the corresponding element table entry is 

updated and all associated procedure table entries are updated. In this step, 

performance is affected by 

• The amount of element text to copy. 

• The amount of work area provided for the I/O buffer (W in the standard method work 

area formula described in 8.4.4.1). 

• The number of elements with element text to copy. 

• The specification for the REDUCE_IO condition item in the function packet. 

7830 9796–013 C–1


Consider two nearly identical files, each with 100 elements. In the first file, the first 

element is deleted and in the second file, the last (100th) element is deleted. 

• For the first file, the text of all 99 undeleted elements is copied to close up the file 

and remove the element text associated with the first element. For this file, all 

element entries and associated procedure table entries must also be updated. 

• For the second file, none of the text of the 99 undeleted elements is copied since 

the deleted text follows the text of the first 99 elements. For this file, no updates to 

element entries or procedure table entries are required. 

The performance for the first file where updates are required to all element entries, all 

procedure table entries, and all element text is much slower than for the second file 

where no updates are required. 

Another consideration is the presence of Object Module Entry Point Tables, which are 

removed by the PACK_PF function and are located in the element text area of the file. 

Even if there are no deleted elements in a file, there may by one or more Object Module 

Entry Point Tables to be removed. For example, if when the second file described earlier 

was created, a PCFP PREP_PF function or a FURPUR @PACK,P or @PREP command 

was performed immediately after the first element was written to the file, an Object 

Module Entry Point Table is written between the text for elements 1 and 2. When the 

file is packed, the element text for elements 2 – 99 is copied to close up the file and 

remove the Object Module Entry Point Table. The element entry and procedure table 

entries for each of these elements also require updates. 

The ACQ_BASIC_PF_INFO function with GET_SUMMARY_INFO = TRUE can be used to 

return the values DEAD_SPACE, PACK_PF_NUM_ELTS_TO_UPDATE, and 

PACK_PF_TEXT_SIZE_TO_COPY. Both deleted elements and Object Module Entry Point 

Tables are considered when these values are calculated. The last two values indicate 

the exact number of elements that require updates and the amount of element text that 

would have to be copied by PACK_PF to close up the file. 

When the amount of element text to copy is large, it is very important that sufficient 

work area be provided for the I/O buffer used during the text copy. To maximize 

function performance, follow the recommendations for W in 8.4.4.1. 

During the second step, each time element text is copied, text pointers in the element 

entry and in the associated procedure table entries must be updated to correctly identify 

the new location of the element text. The default action is to immediately write the 

updated entries to mass storage. The smallest write performed is one 28-word sector. 

Therefore, writing each 10 word element entry results in 28 words being written, or 56 

words being written when the element entry spans two sectors. This means that each 

sector is written multiple times as element entries are updated. For the element table, 

each sector is written an average of 3.6 times. For 4-word procedure table entries, each 

28-word sector is written an average of seven times. This combination of writing 

sectors multiple times and numerous small writes is extremely inefficient, and results in 

a very significant decrease in performance for the default action. 

C–2 7830 9796–013


This is the reason for the REDUCE_IO function packet condition item. When this item is 

set to TRUE, updated element table entries and procedure table entries are not 

immediately written to mass storage. Instead, the writes are delayed until after the 

element text for all elements has been copied. Then, the entire element table and each 

of the updated procedure tables are written with a single I/O request. Replacing multiple 

writes of small buffers with single writes of large buffers reduce the total amount of I/O 

and the total number of I/O requests. This increases the efficiency of the I/O and the 

overall performance of the function. Note that specification of REDUCE_IO does affect 

the contents of the file in case of system or function failure as described in C.4. 

The size of the element text to be copied during a standard method pack is usually much 

larger than the size of the program file element table and procedure tables. For this 

reason, a greater performance benefit is usually realized by providing the recommended 

I/O buffer in the work area formula rather than by specifying REDUCE_IO in the function 

packet. To illustrate this, the standard method is used to pack a file with 200 elements, 

the first of which is deleted, with no procedure tables and with each element having one 

track (1,792 words) of element text. Table C–1 shows the performance results while 

using the minimum I/O buffer size of 112 and the recommended I/O buffer size of 1,792 

and with REDUCE_IO equal to both FALSE and TRUE. Table C–1 lists the average 

elapsed time (wall clock time) for the PACK_PF function and the total Standard Unit of 

Processing (SUP) time in seconds. The results were obtained on a nearly idle 2200/524 

system and were averaged over a minimum of 10 function repetitions. Results on 

different 2200 IX models may vary. 

Table C–1. Standard Method Performance Comparison 

I/O Buffer Size REDUCE_IO=FALSE REDUCE_IO=TRUE 

112 76 seconds 

212 SUP seconds 

1792 9 seconds 

Notes: 


73 seconds 


5 seconds 


• In all four cases, the average elapsed time and the SUP seconds during the first step 

of the standard method were identical and were less than 0.2 seconds. The 

remainder of the time was spent during the second step of the standard method. 

• When the I/O buffer is increased from 112 to 1,792 words and REDUCE_IO is 

FALSE, PACK_PF takes an average of only 12 percent of the elapsed time and 11 

percent of the SUPs. 

• Setting REDUCE_IO to TRUE with the 112-word I/O buffer does not result in much 

of a performance improvement. 

• The best results are achieved with the recommended I/O buffer of 1,792 words and 

REDUCE_IO is TRUE (1,792/TRUE). Compared to 112/FALSE, 1,792/TRUE takes an 

average of only 7 percent of the elapsed time and 8 percent of the SUPs. Compared 

to 1,792/FALSE, 1,792/TRUE takes an average of 56 percent of the elapsed time and 

74 percent of the SUPs. 

7830 9796–013 C–3


• 1,792 words is used for the recommended I/O buffer size because this is the size of 

the largest element to be copied in the file. See 8.4.4.1 for the complete description 

of the I/O buffer size recommendation. 

C.2. Copy Method Performance 

The copy method uses a two-step process to pack a file, as described in 8.4. The first 

step uses the COPY_ELT function to copy undeleted elements, associated procedure 

table entries, and associated element text to a temporary file. The second step uses the 

COPY_RAF_RAF function to copy the temporary file back to the program file. In the 

standard method, the number of elements copied and the performance of the function 

can be affected by the location of deleted elements in the file and by the presence of 

Object Module Entry Point Tables in the file. The copy method always copies all 

undeleted elements, procedure table entries, and element text twice, once during each 

step. The performance of the function depends mainly on the amount of element text to 

copy and the work area provided. The number of elements and text size to copy can be 

derived from values returned by the ACQ_BASIC_PF_INFO function with 

GET_SUMMARY_INFO = TRUE. The number of elements to copy is 

ELT_NUM_ENTRIES - NUM_DELETED_ELTS. The text size to copy in words is 

TEXT_SIZE - DEAD_SPACE. 

In the first step work area formula (see 8.4.4.2), it is crucial for maximum performance to 

provide the recommended values for D (temporary file element table buffer) and I (I/O 

buffer). The value of I in this formula is nearly identical, except for the minimum allowed, 

to the value of W in the standard method formula (see 8.4.4.1). The value for C controls 

the efficiency of procedure table copy operations. For maximum efficiency, provide 

three words for each undeleted procedure element. If the file contains over 50 

undeleted procedure elements, a minimum of 153 words must be provided for C. The 

recommended value for S is the initial size of the program file element table buffer. This 

value has the least affect on function performance. If possible, the recommended value 

should be provided. If necessary, the value for S can be reduced to its minimum value of 

252 without seriously impacting function performance. 

Unlike the standard method, where the vast majority of work is performed by the second 

step, the work performed by the copy method is more evenly divided between the first 

and second steps. When the recommended work area is provided for both steps, the 

elapsed time and SUP seconds are larger for the first step than for the second step. This 

is because the first step copies each element, its procedures, and its text separately 

while the second step uses multiple activities to copy tracks in groups without regard to 

the file structure. The percentage of time taken by each step is largely dependent on the 

average element text size per element. For files averaging one track of element text per 

element, the first step takes approximately 90 percent of the elapsed time and 80 

percent of the SUP seconds. As the average element text size per element decreases 

to the minimum size of 28 words per element, the first step percentages rise to 99 

percent of the elapsed time and 95 percent of the SUP seconds. As the average 

element text size per element increases to four tracks, the first step percentages fall to 

75 percent of the elapsed time and 60 percent of the SUP seconds. 

C–4 7830 9796–013


Table C–1 shows the standard method performance with different I/O buffer sizes and 

settings for the function packet REDUCE_IO item. Using the same file (200 elements 

with the first element deleted, no procedure tables, and each element having one track 

of element text), Table C–2 shows the copy method performance with the minimum 

work area size (4,570 words), the work area size recommended for the first step (6,504 

words), the second step (30,470 words), and the maximum work area size for the 

second step (60,070 words). The Function Performance column shows the total 

performance of the function. The next two columns divide the performance between 

the two copy method steps. Like Table C–1, this table lists both the average elapsed 

time and the total SUP seconds used. The results were obtained on a nearly idle 

2200/524 system and were averaged over a minimum of 10 function repetitions. 

Results on different 2200 IX models may vary. 

Work Area Size 

Table C–2. Copy Method Performance Comparison 

4,570 9 seconds 

Function 

Performance 







Notes: 


First Step 

Performance 

5 seconds 


5 seconds 


5 seconds 


5 seconds 


Second Step 

Performance 

3 seconds 


3 seconds 


1 second 

7 SUP seconds 

1 second 

6 SUP seconds 

• Since the table values are rounded to the nearest second, the total values do not 

always equal the sum of the first and second steps. 

• For both 4,570 and 6,504, the I/O buffer size for both the first and second steps is 

1,792 words. 

• The first step performance improves only fractionally for work area sizes greater than 

the recommended value of 6,504 words. 

• For all work area sizes, the elapsed times are at least as good as those listed in Table 

C-1 (standard method) with a 1,792 word I/O buffer and REDUCE_IO = FALSE 

(1,792/FALSE). 

• For 30,470 and 60,070, the SUP seconds are similar to Table C-1 (standard method) 

1,792/FALSE and the elapsed times are similar to 1,792/TRUE. 

7830 9796–013 C–5


C.3. Performance Comparison 

Tables C–1 and C–2 compare the PACK_PF performance of the standard method to the 

copy method for one small, 200-element file. This is only one performance example. 

This subsection generally compares the performance of the standard method to the copy 

method. These comparisons assume that the work area provided conforms to the 

recommendations described in 8.4.4. 

The following items relate to the PACK_PF performance comparisons: 

• Elapsed time or wall clock time is the most variable performance measurement, 

varying widely depending on the time of day, system activity, subsystem activity, 

and so forth. Identical PACK_PF functions on identical files may have widely varied 

elapsed times, even when performed consecutively. 

• SUP seconds retrieved by ER INFO$ are the most consistent performance 

measurement, although the results do not always correlate directly to the observed 

performance. 

• In almost all cases, assuming the same number of elements to update and the same 

amount of text to copy, the standard method with REDUCE_IO = TRUE is the 

fastest followed by the copy method. The standard method with REDUCE_IO = 

FALSE is the slowest . 

• For a medium size file of 1,000 elements, each with one track (1,792 words) of text, 

the following are the approximate performance ratios of the standard method with 

REDUCE_IO = TRUE : copy method : standard method with REDUCE_IO = FALSE. 

− For elapsed time, the ratio is 1 : 1.10 : 2.50 

− For SUP seconds, the ratio is 1 : 1.25 : 1.40 

• As the number of elements increases to large files of 10,000 elements and more, 

the performance ratios for both elapsed time and SUP seconds remain nearly 

unchanged. 

• As the number of elements decreases to small files of 100 elements, the relative 

performance of the copy method becomes slower and the relative performance of 

the standard method with REDUCE_IO = FALSE becomes faster, as follows: 

− For elapsed time, the ratio is 1 : 1.60 : 2.20 

− For SUP seconds, the ratio is 1 : 1.65 : 1.40 

• As the average text size per element increases, the relative performance of the copy 

method is nearly unchanged in terms of elapsed time, but becomes much slower in 

terms of SUP seconds. The standard method with REDUCE_IO = FALSE becomes 

faster, both in terms of elapsed time and SUP seconds. 

• The ACQ_BASIC_PF_INFO return item PACK_PF_NUM_ELTS_TO_UPDATE is the 

number of elements that will be updated by the standard method and the difference 

between ACQ_BASIC_PF_INFO return items ELT_NUM_ENTRIES and 

NUM_DELETED_ELTS is the number of undeleted elements that will be copied by 

the copy method. As the ratio of the first item to the second decreases, the 

performance of the standard method for both REDUCE_IO values improves against 

the copy method. 

C–6 7830 9796–013

C.4. File Contents in Error Cases 


As with any PCFP function that modifies a file, a system failure or function error during a 

PACK_PF may leave the file in an indeterminate state. To avoid the possibility of lost or 

inaccessible data, insure that there is a current back-up copy of the file available before 

performing a PACK_PF function. In most cases, following a system or function failure it 

is not possible to determine the state of the file. None of the PCFP program file 

information functions described in Section 6 or the FURPUR @PRT,TL command can be 

used to verify the validity of the file contents. For most error scenarios, it may appear 

from the Table of Contents that the PACK_PF function has completed, when actually not 

all of the program file tables have been updated and not all of the element text has been 

copied. In all cases of system failure or function failure, it is recommended that the file 

be reloaded from its backup copy. 

The following paragraphs describe the pack methods with particular regard to the 

contents of the file in various error scenarios. 

The first step of the standard method removes all deleted elements and procedure table 

entries and rewrites the tables in the following order: 

1. Element Table 

2. Assembler Procedure Table 

3. COBOL Procedure Table 

4. FORTRAN/PLUS Procedure Table 

5. File Table Index (FTI) 

Since the FTI, which contains the size of individual tables is the last table written, a 

failure during this step is likely to leave the program file with inconsistent or invalid tables 

consisting of entries from both before and after the pack. Since the first step is usually a 

very small percentage of the total elapsed time for the function, this scenario is much 

less likely than a failure during the second step. 

When the first step has been successfully completed, the deleted entries have been 

removed from the program file tables but no text has been copied. During the second 

step, the contents of the file in case of a failure depend on the selected value of 

REDUCE_IO. 

When REDUCE_IO is FALSE (default), each element entry and its associated procedure 

table entries are rewritten to their tables immediately after copying the element text for 

the entry. This means that only the element being processed at the time of a failure is 

affected. Typically, a failure results in the element text being partially overwritten or in 

procedure table entries referencing incorrect mass storage addresses. However, it is 

difficult to determine which element has been affected by the failure. 

7830 9796–013 C–7


When REDUCE_IO is TRUE, the element entries and procedure table entries are not 

rewritten to their tables until after all of the element text for the file is copied. This 

means that all of the element entries and procedure table entries for which element text 

has been copied are affected in case of a failure. Typically, a failure results in the 

element text of each affected element being overwritten and in each affected procedure 

table entry referencing an incorrect mass storage address. Even though the number of 

elements affected in case of a failure is much greater, the improved performance offered 

with REDUCE_IO = TRUE means that the elapsed time that the file is vulnerable to a 

failure is much smaller. 

The copy method offers the best combination of performance and file safety. This is 

because the file is not modified in any way during the first step, which takes a majority 

of the elapsed time for the function. The file is not modified until the second step, when 

the temporary file created during the first step is copied back to the original file. The file 

is copied sequentially from the first track to the end of the element text. This means 

that these items are written in the following order followed by the tracks of element 

text: 

1. FTI 

2. Element Table 

3. Assembler Procedure Table 

4. COBOL Procedure Table 

5. FORTRAN/PLUS Procedure Table 

If the program file tables are only partially written when a failure occurs, it is likely to 

leave the program file with inconsistent or invalid tables consisting of entries from both 

before and after the pack. This is similar to a failure during the first step of the standard 

method. Since the program file tables are usually much smaller than the element text, 

the more likely error scenario is that the element text was only partially written at the 

time of the failure. In this case, elements would have invalid text. 

C–8 7830 9796–013

Glossary 

A 

absolute cycle 

See F-cycle, element cycle. 

absolute element 

A type of element that is ready for execution on an 1100/2200 processor or one that 

contains a special definition called a subsystem definition. There are five subtypes of 

absolute elements: absolute (ABS), object module (OM), bound object module (BOM), 

zero overhead object module (ZOOM), and subsystem definition (SSD). 

access control record (ACR) 

A record containing a list of users, the accesses they may have to a file, and the 

conditions under which they are allowed access. Attaching an ACR to a file makes the 

file semiprivate. 

account-id 

An identifier specifying an account charged with processing time and system resources 

consumed during a run. Also called account number. You can use account identifiers to 

control access to objects by specifying them in ACRs. 

arithmetic fault modes 

The two modes that indicate how an 1100/2200 processor should handle certain 

floating-point errors. The two modes are noninterrupt and compatible. 

array 

B 

A series of data items or data structures, all of the same form. 

Basic Services Package (BSP) 

A set of program-callable routines in the system library for handling and updating the 

table of contents (TOC) in a program file. 

block numbering 

A hardware block number appended to each data block written to tape. This block 

number helps with error recovery of data by allowing the detection of tape movement. 

Block numbering also helps to ensure data integrity by making it easier to detect extra or 

missing data blocks. 

block size 

The size of a physical data block written to tape. Under the FURPUR tape format, the 

block size is always a multiple of a track (1,792 words). 

7830 9796–013 Glossary–1

Glossary 

C 

calling program 

In the context of this reference manual, a calling program is a program written in C, 

COBOL, or FORTRAN, which calls one or more functions of PCFP. 

cataloged file 

A file known to and retained by the Executive, for an indefinite period not necessarily 

related to the life of a particular run, and generally usable by runs other than the run 

which originally created the file. See also lifetime, temporary file. 

character item 

A data item that contains ASCII character strings in structures used to interface with 

PCFP. For each character item, the maximum length of the string is given in the item 

description. 

checksum 

A software data integrity scheme that can be used for data written to tape. A checksum 

is computed by taking the arithmetic sum of every word in a track of data, and writing 

this value to tape along with the track. When the data is read from tape, the checksum 

is computed once again. A checksum error occurs if the checksum computed when the 

data is read does not match the checksum that was computed when the data was 

written. 

clearance level 

A hierarchical classification for files for security purposes. Clearance levels can range 

from 0 to 63, with 63 being the most restrictive. Clearance levels can also be associated 

with symbolic labels such as unclassified, classified, secret, and top secret. 

condition item 

A data item that can assume only the values TRUE and FALSE. Internally, TRUE is 

represented by 1, and FALSE is represented by 0. 

conformance to standard calling sequence 

See standard calling sequence. 

copy procedure 

A part of a symbolic element that you dynamically include as part of a COBOL program 

using the COPY statement. The copy procedures supplied with PCFP have been 

processed by the PDP processor, and reside in program file SYS$LIB$*PROC$, which is 

searched automatically by the COBOL compiler. See also include element, include 

procedure. 

COPY,G format 

See FURPUR format. 

cycle 


Glossary–2 7830 9796–013

D 

Glossary 

data compression 

A hardware feature on certain tape subsystems that reduces the amount of physical tape 

required to record data by removing repetitive information before recording it. This 

feature compresses data that is written to tape by a ratio of 3:1 or better. In order to use 

data compression, you must also use block numbering. 

data item 

A data entity that contains a single value. Sometimes referred to simply as item. 

data structure 

A data entity composed of several data items that are considered as a unit. Sometimes 

called a packet. PCFP parameters are data structures. 

date-time item 

A data item that can assume date and time values. All date-time items are two words 

long, and contain the subitems year, month, day, and milliseconds. 

default value 

In the context of this Reference Manual, the default value of an item is the value whose 

internal representation is zero. Thus, when a calling program zero-fills a data structure, it 

sets all items in that structure to their default values. At that point, the calling program 

needs to assign values explicitly only to those items that require a nondefault value. For 

character items, the default value is null. 

deleted element 

An element in a program file that is marked for removal from the file. 

density 

The amount of data stored per unit length or area of a storage medium, such as tape. 

Tape density is measured in bits per inch. 

destination file 

The file into which data is written during a copy operation. 

directory-id 

An identifier used to distinguish between the master file directories in a file-sharing 

environment. Each directory has a directory-id for use in file creation and assignment. 

Shared files use the SHARED directory-id and local files use the STD (standard) 

directory-id. 

E 

element 

A named unit of data within a program file. The nature of the data within an element 

depends on the type the element, which is one of the following: absolute, omnibus, 

relocatable, or symbolic. Within a program file, each undeleted element is uniquely 

identified by the combination of its name, version, and type. 

7830 9796–013 Glossary–3

Glossary 

element cycle 

One of the stages a symbolic element goes through as it is updated. Also called a 

symbolic element cycle. A specific element cycle is identified by one of two numbers: 

an absolute element cycle number or a relative element cycle number. An absolute 

element cycle number must be between 0 and 62 inclusive, and does not change as 

new element cycles are created. A relative element cycle number must be between -62 

and 0 inclusive, and indicates a particular element cycle relative to the current cycle. 

Relative element cycle numbers change as new element cycles are created. 

element subtype 

A further classification of elements beyond the type classification. The subtype of an 

element typically indicates the system processor that produced or can process the 

element. 

element table 

A table within a program file's table of contents. Each entry within this table identifies 

and describes a unique element in the program file. 

element type 

One of the basic classifications of elements, based upon the nature of the data in the 

element. The four element types are absolute, omnibus, relocatable, and symbolic. 

ELMS 

See Extended Language Message System. 

entry point 

A location within a relocatable element or an object module that can be referenced by 

other relocatable elements or object modules respectively. There are two types of entry 

points: those occurring in relocatable elements (relocatable entry points), and those 

occurring in object modules (object module entry points). 

entry point table 

A table within a program file's table of contents containing entries that describe all of the 

entry points of a specific type in the program file. There are two entry point tables, one 

that describes relocatable entry points and one that describes object module entry 

points. 

EOF mark 

A hardware code that indicates there is no more data in a logical file on tape. On 

magnetic tape, an EOF mark is written after each logical file, and two EOF marks are 

written to indicate the logical end of the tape file. Also called end-of-file mark. 

error 

A situation that was detected during execution of a PCFP function that prevented 

completion of the function. The nature of the error is returned as an error code to the 


Glossary–4 7830 9796–013

Glossary 

error code 

The value returned by each PCFP function to calling programs written in C and 

FORTRAN. Also, an item in the generic part of the function packet that contains the 

same value. The error code indicates the warning condition or error (if any) that occurred 

during processing of a PCFP function. The form of the error codes returned by PCFP is 

an ELMS condition-id, which can be supplied as a parameter to ELMS to produce an 

explanatory message. 

exclusive assign 

The assignment of a file such that the run making the assignment is the only run that can 

access the file (@ASG,AX). Access by other runs is denied until the exclusive 

assignment is released. 

Extended Language Message System (ELMS) 

A message processing system used by software applications in the OS 2200 

environment. When an application uses ELMS for message processing, the messages 

are defined, maintained, and processed separately from the application. This gives the 

application independence from its messages and the run-time environment. 

F 

F-cycle 

One of the stages a file goes through as it is updated. Also called a file cycle. A specific 

F-cycle is identified by one of two numbers: an absolute F-cycle number or a relative 

F-cycle number. An absolute F-cycle number must be between 1 and 999 inclusive, and 

does not change as new F-cycles are created. A relative F-cycle number must be 

between -31 and +1 inclusive, and indicates a particular F-cycle relative to the current 

cycle. Relative F-cycle numbers change as new F-cycles are created. 

F-cycle series 

A collection of files with the same directory-id, qualifier, and file name but with different 

F-cycle (file cycle) numbers. Up to 32 files can exist in a single F-cycle series. 

file 

An area of storage used to contain programs or data. A file can be random access (RAF) 

or sequential access (SAF). The lifetime of a file can be temporary or cataloged. 

file identifier 

A parameter of many PCFP functions that uniquely identifies the file or one of the files 

on which the function is to operate. The file identifier data structure contains items that 

specify the directory-id, qualifier, file name, F-cycle, read key, and write key of the file on 

which the function is to operate. 

file owner 

The user that controls access to a file by other users. Initially, the owner of a file is the 

user that created the file. 

file sharing 

See Multi-Host File Sharing (MHFS). 

7830 9796–013 Glossary–5

Glossary 

function 

A subroutine that performs a specific operation and returns a value to the calling 

program. A program invokes PCFP by calling one of the functions defined for PCFP. 

function packet 

The first parameter of all PCFP functions. It acts both as an input parameter and as an 

output parameter. It is the data structure through which the calling program specifies all 

options that apply to the function, and through which PCFP passes certain fixed-size 

return information back to the calling program. Function packets consist of a generic 

part, a return-information part (some functions only), and a specific part. 

FURPUR 

A set of file utility routines that are part of the OS 2200 Operating System. In 

conjunction with the Executive, FURPUR provides the user with a simplified method of 

controlling and moving data within OS 2200 files and elements. 

FURPUR format 

A tape format used to encode a logical file on a sequential-access file. Sometimes called 

COPY,G format. The first block of the logical file is a 28-word logical file descriptor, 

which contains the following information about the logical file: file name, qualifier, 

F-cycle, highest track written, date and time of copy, equipment code, block size. 

Subsequent blocks of the logical file contain 1 to 16 tracks of data, with each track 

preceded by a two-word track header containing the track sequence number, the 

checksum for the track (optional), the mass storage address of the track, and the 

indicator for last track of the logical file. There are two minor variations of the FURPUR 

tape format: the revised variant, which is the default written by PCFP, and the obsolete 

variant, which is written by the FURPUR @COPY,G command and can be written by 

PCFP. The revised variant offers performance improvements over the obsolete variant, 

and should be used whenever possible. Both PCFP and FURPUR can read both variants 

of the FURPUR tape format. 

G 

generic part of function packet 

The part of the function packet for each PCFP function that is the same for every PCFP 

function. The generic part of each function packet is contained in the first ten words of 

the function packet. 

granule 

I 

The increment by which storage space is allocated to a mass storage file. A granule can 

be either a track (1,792 words) or a position (64 tracks). 

include element 

A symbolic element that you dynamically include as part of a C program using the 

#include statement. The include elements supplied with PCFP reside in program file 

SYS$LIB$*PROC$, which is searched automatically by the C compiler. See also copy 

procedure, include procedure. 

Glossary–6 7830 9796–013

Glossary 

include procedure 

A part of a symbolic element that you dynamically include as part of a FORTRAN 

program using the INCLUDE statement. The include procedures supplied with PCFP 

have been processed by the PDP processor, and reside in program file 

SYS$LIB$*PROC$, which is searched automatically by the FORTRAN compiler. See also 

copy procedure, include element. 

initial reserve 

The mass storage space that is allocated to a mass storage file upon its inception. 

integer item 

A data item that can assume numeric values in structures used to interface with PCFP. 

Each integer item can either be signed, which implies that it can contain either zero, a 

positive number, or a negative number, or it can be unsigned, which implies that it can 

contain only zero or a positive number. 

internal name 

An alternate name for a file, given to the file with an @USE control statement. The 

original name of the file (the name given to the file when it was created) is called an 

external file name. Internal file names, also called use names, are used to simplify file 

references (when the external file name is long), to differentiate between files that have 

the same basic file name but different qualifiers or F-cycles, and to associate internally 

programmed names with specific files. 

item 

L 

labeling 

See data item. 

See tape labeling. 

large element program file 

A program file format that is capable of containing elements that have over 262,143 

sectors of element text. A large element program file can be initialized with the small, 

variable length table structure of a standard program file or with the large, fixed length 

table structure of a large program file. See also large program file, program file, and 

standard program file. 

large program file 

A program file format that has large, fixed length tables. The element table can contain 

up to 26,146 elements. Each element can contain up to 262,143 sectors of element 

text. See also large element program file, program file, and standard program file. 

LEPF 

lifetime 

See large element program file. 

The property of a file that indicates its longevity. The two types of file longevity are 

temporary and cataloged. 

7830 9796–013 Glossary–7

Glossary 

logical end 

The position on a tape file immediately following the last logical file on the tape. 

Sometimes called end of recorded area. When a tape file is positioned at its logical end, 

a logical file cannot be copied from the tape file, but a logical file can be written to the 

tape file without destroying any data already on the tape file. On an unlabeled tape file, 

the logical end is indicated by two consecutive EOF marks; on a labeled tape file, it is 

indicated by a special software EOF label. 

logical file 

The data contained on a sequential-access file that corresponds with a single 

random-access file. On an unlabeled tape file, a logical file is delimited by EOF marks; on 

a labeled tape file, a logical file is delimited by EOF marks along with special header and 

trailer labels. A logical file can span volumes of a tape file. 

logical file descriptor 

The initial block of data in a logical file on tape. It describes the characteristics of the 

logical file but does not contain any data of the logical file. 

logical file position 

An integer denoting the position of a logical file on a volume of a sequential-access file. 

The first logical file on a volume has the logical file position of 1, and the logical file 

position of each subsequent logical file is 1 greater than the previous. PCFP considers a 

tape to be positioned at a particular logical file if the physical position of the tape is 

anywhere between the EOF marks that delimit the logical file. 

LPF 

M 

See large program file. 

mass storage 

The auxiliary storage that has random-access capability as opposed to, for example, 

magnetic tape. Includes all types of disks and solid-state storage. 

master file directory (MFD) 

The directory maintained by the Executive to control cataloged files. Files listed in the 

MFD are retained even after a run terminates. 

Multi-Host File Sharing (MHFS) 

A feature of the Executive that allows independent closely or loosely coupled system 

hosts to access a set of shared mass storage devices. MHFS associates each Executive 

file with either a local file directory or a shared file directory, and handles the interhost 

communications necessary to deal with file sharing across multiple hosts. 

N 

null 

The value of a character string whose first character is the null character. Since any 

character after a null character is disregarded, the value of the entire character string is 

considered to be null. Also called null value. 

Glossary–8 7830 9796–013

null character 

The ASCII character whose internal value is binary zero. 

Glossary 

null-terminated 

An ASCII character string whose end is indicated by the null character. Any characters 

that follow the null character are disregarded. Contrast with space-filled. 

O 

object module 

See absolute element. 

omnibus element 

A type of element that contains information in a more flexible format than the other 

element types provide. The actual format of the data in an omnibus element depends on 

the processor that produced it. Omnibus elements are further classified by subtype, 

which indicates which system processor produced, or can process, the data within the 

element. 

owner 

P 

See file owner. 

parameter 

In the context of this reference manual, a parameter is a data structure that is passed by 

the calling program as information to a PCFP function. 

partial string specification 

The use of wild-card characters in a character string to specify only a part of a character 

value that PCFP must match. Also called partial name specification. 

PF 

See standard program file. 

physical end of volume 

The point on a tape volume at which no more data can be read from or written to the 

volume. When a tape file reaches this point, a swap must occur before any further data 

can be read from or written to the tape file. 

physical position 

The physical point along a volume of tape at which the read-write heads of the tape unit 

are currently positioned. 

position 

(1) An increment for measuring mass storage space, equal to 64 tracks, 4,096 sectors, or 

114,688 words. (2) The current placement of a magnetic tape in relationship to the 

read/write heads of the tape unit. See also physical position, logical file position. 

7830 9796–013 Glossary–9

Glossary 

preamble 

A discrete part of a relocatable element that identifies and describes the following 

entities within the element: location counters, entry points, and external references. In 

addition, the preamble contains other information about the relocatable element that is 

used during a collection process involving this element. 

prep 

privacy 

private 

The process of building one or both entry point tables in a program file. 

The discretionary access control given to a file at the discretion of the owner. The 

controls are discretionary in the sense that the file's owner can pass permission (perhaps 

indirectly) on to any other user within the mandatory bounds of control. For owned files, 

the levels of privacy are private, semiprivate, and public. For unowned files, the privacy 

levels are private and public. 

One of the levels of privacy for a file. For an owned private file, only the owner can 

access the file. For an unowned private file, only a run with the correct account-id or 

project-id can access the file. 

procedure 

A set of statements that is stored apart from a program within a symbolic element, and 

is dynamically included with the program when it is compiled or assembled. Procedures 

are used most often when the same instructions must be included in different programs. 

Four computer languages can use procedures: MASM, COBOL, FORTRAN, and PLUS. 

See also copy procedure, include procedure. 

procedure symbolic element 

One of four symbolic element subtypes that can contain procedures. These subtypes 

are ASMP (MASM procedures), COBP (COBOL procedures), FORP (FORTRAN 

procedures), and PSP (PLUS procedures). 

procedure table 

One of three tables in the table of contents of a program file. A procedure table is used 

to locate the procedures contained in the program file. Each entry in a procedure table 

contains the name of a procedure, the sequence number of the element that contains 

the procedure, and the location of the procedure text. One procedure table contains 

MASM procedures, one contains COBOL procedures, and one contains FORTRAN and 

PLUS procedures. 

program file 

A partitioned random-access file consisting of a group of elements residing on mass 

storage. 

project-id 

An identifier used to label a run for file access control. It may also classify unowned 

files. It is also used as a grouping mechanism within ACRs. 

public 

One of the levels of privacy for a file. Any user on the system can access a public file. 

Glossary–10 7830 9796–013

Q 

Glossary 

quota group 

Under the quota system, a grouping of mass storage equipment types specified by the 

site administrator. 

R 

random-access file (RAF) 

A data file that is read randomly. Random-access files operated on by PCFP are 

contained on mass storage. Sometimes called a mass storage file. 

relative cycle 


relocatable element 

A type of element produced by some compilers that contains machine instructions that 

must still undergo the process of collection before they can be executed. 

return area 

An output parameter used by some PCFP functions for the return of a variable-length 

array of data structures to the calling program. Each entry in the array returned by PCFP 

is called a return entry. The return area parameter is described in the return-information 

part of the function packet. 

return entry 

A single occurrence in the array of information that some PCFP functions return to the 

calling program in the return area. 

return-information part of function packet 

The part of the function packet that describes the return area used by the function. This 

part of the function packet is present only for those functions that have a return area 

parameter. For those function packets that contain a return-information part, it follows 

immediately after the generic part. 

S 

sector 

An increment for measuring mass storage space, equal to 28 words. 

sector-addressable 

Pertaining to mass storage that can be accessed in units of 28 words (one sector). 

security-ownership feature 

An Executive feature that assigns ownership to a file based on a user-id access system. 

It classifies three types of ownership modes: public, private, and semiprivate. A file with 

public ownership is accessible by all users. A file with private ownership is accessible 

only by the user that created the file. A file with semiprivate ownership is accessible 

only by users named in an ACR. 

7830 9796–013 Glossary–11

Glossary 

semiprivate 

One of the levels of privacy for a file. A semiprivate file has an ACR attached to it. Only 

an owned file can be semiprivate. The owner of a semiprivate file has all types of access 

to the file. Other users have access to the file depending on the conditions specified in 

the ACR. 

sequence number 

An integer denoting an element's position within a program file. An element whose 

sequence number is 3 is described by the third entry in the element table of the program 

file. 

Sequential-access file (SAF) 

A data file that is read sequentially. Sequential-access files operated on by PCFP are 

contained on tape. Sometimes called a tape file. 

site info 

A half-word of information in the MFD entry of a cataloged file, which can be used by a 

site in whatever manner it chooses. The information is stored in H2 of word 12 of sector 

0 of the MFD main item associated with each cataloged file. 

source file 

The file from which data is read during a copy operation. 

space-filled 

An ASCII character string in which the significant characters are followed by a series of 

space characters out to the maximum size of the string. Contrast with null-terminated. 

specific part of function packet 

The part of the function packet that contains items unique to a particular function. This 

part of the function packet varies in size depending on the function, and is always the 

last part of the function packet. 

standard calling sequence (SCS) 

A set of standard conventions for compiler programs that controls parameter passing. It 

generally eliminates the need for interface routines for programs written in different 

compiler languages, allowing an application to be written in several languages. There are 

three levels of conformance to the standard calling sequence: none, loose, and strict. 

standard program file 

A program file format that has small, variable length tables. The element table can 

normally contain up to 2,671 elements but can be expanded to contain up to 5,000 

elements. Each element can contain up to 262,143 sectors of element text. See also 

large element program file, large program file, and program file. 

structure 

See data structure. 

swap 

The unmounting of one volume of a sequential-access file followed by the mounting of 

another volume. A swap typically occurs when the physical end of a volume of an SAF is 

reached during reading or writing of the SAF: after the swap, the read or write operation 

continues at the start of the next volume of the SAF. A swap can also result from a 

MOVE_SAF operation. 

Glossary–12 7830 9796–013

Glossary 


A type of element that contains symbolic images. A symbolic element can contain a 

source program, directives for a processor, a runstream, or data. The images in a 

symbolic element are in system data format (SDF). Symbolic elements are further 

classified by subtype, which indicates which system processor produced, or can 

process, the images within the element. 

symbolic element cycle 

See element cycle. 

system data format (SDF) 

A sequential access, variable record length, file format that is used by 1100/2200 system 

software for storage of symbolic data. 

T 

table of contents (TOC) 

A directory within a program file that is used to keep track of elements, entry points, and 

procedures within the file. The table of contents consists of six tables: an element table, 

three procedure tables, and two entry point tables. 

tape 

A strip of material used for auxiliary storage. A tape has sequential-access capability as 

opposed to, for example, mass storage capability. Includes all types of magnetic tape 

subsystems. 

tape format 

A software convention used to encode the data contained in a logical file on a tape file. 

At the present time, PCFP can only read and write logical files using the FURPUR format. 

tape labeling 

A software system of security labels on a volume of tape specifying the mandatory 

attributes (clearance level and compartment set) and the discretionary attributes (access 

list) associated with the data stored on the volume. 

temporary file 

A file that exists only for the duration of the run. When the run terminates or the file is 

released from the run, the file ceases to exist. You create a temporary file with the 

@ASG,T statement. See also lifetime, cataloged file. 

track 

An increment for measuring mass storage space. Equal to 1,792 words or 64 sectors. 

track sequence number 

An integer denoting the location of a track of data stored in a logical file on a tape file. 

Track sequence numbers start with 0 for the first track of a logical file, and increase by 1 

for each track. Under the FURPUR tape format, the track sequence number of each 

track is stored in the track header associated with that track. 

7830 9796–013 Glossary–13

Glossary 

U 

undeleted element 

An element in a program file that is not marked as deleted. 

user-id 

V 

A string of 12 characters that is used to identify a person using the system. 

value-list item 

A data item that can assume a defined set of values with explicit names. For each such 

item, the set of values, along with their internal integer codes, are listed in the item 

description. 

volume 

W 

One physical unit of storage medium. For magnetic tape, a volume is a reel or a 

cartridge. For mass storage, a volume is a disk pack. The volumes that compose a file 

are specified when the file is cataloged or assigned. 

warning condition 

A special situation that was detected during execution of a PCFP function that did not 

prevent completion of the function. The nature of the warning is returned as an error 

code to the calling program. 

wild-card character 

One of two special characters that a calling program can specify in certain character 

strings it supplies to PCFP. These characters allow partial specification of a string that 

PCFP is to match. The question mark character ( ? ) can match any single character. The 

asterisk character ( * ) can match any string of zero or more characters. 

word 

The smallest addressable unit of data, consisting of 36 bits. 

word-addressable 

Pertaining to mass storage that can be accessed in units of a single word. 

work area 

A scratch data area used by each PCFP function to perform its operations. The calling 

program does not supply the work area for PCFP, as PCFP allocates and releases this 

space dynamically. However, the calling program must specify in the function packet the 

size of the work area that PCFP allocates. 

Glossary–14 7830 9796–013

Z 

zero-fill 

Glossary 

The action of setting an entire data structure or an entire area of mass storage to binary 

zero. Zero-filling a PCFP data structure sets each item within the data structure to its 

default value. 

7830 9796–013 Glossary–15

Glossary 

Glossary–16 7830 9796–013

Index 

A 

acquire basic program file information 

(ACQ_BASIC_PF_INFO) 

defined, 6-1 

parameters, 6-2 

structure definition element, 6-3 

acquire basic program file item descriptions 

COBOL_PROC_NUM_ENTRIES, 6-6 

COBOL_PROC_OPEN_ENTRIES, 6-6 

DEAD_SPACE, 6-8 

ELT_NUM_ENTRIES, 6-6 

ELT_OPEN_ENTRIES, 6-6 

FTN_PLS_PROC_NUM_ENTRIES, 6-6 

FTN_PLS_PROC_OPEN_ENTRIES, 6-7 

GET_SUMMARY_INFO, 6-4 

LARGEST_UNDELETED_TEXT_ SIZE, 6-8 

LATEST_ABS_SEQ_NUM, 6-5 

MASM_PROC_NUM_ENTRIES, 6-6 

MASM_PROC_OPEN_ENTRIES, 6-6 

NEXT_TEXT_LOCATION, 6-5 

NUM_4_WORD_COBOL_PROC_ENTRIES, 

6-8 

NUM_8_WORD_COBOL_PROC_ENTRIES, 

6-9 

NUM_ABS_ELTS, 6-7 

NUM_DELETED_ELTS, 6-8 

NUM_OMN_ELTS, 6-7 

NUM_PR0C_ELTS, 6-8 

NUM_REL_ELTS, 6-7 

NUM_SYM_ELTS, 6-7 

NUM_UNDELETED_PR0C_ELTS, 6-8 

PACK_PF_NUM_ELTS_TO_ UPDATE, 6-9 

PACK_PF_TEXT_SIZE_TO_COPY, 6-10 

REL_EP_NUM_ENTRIES, 6-7 

REL_EP_OPEN_ENTRIES, 6-7 

TEXT_SIZE, 6-5 

TOC_SIZE, 6-5 

acquire element information function 

(ACQ_ELT_INFO) 

defined, 6-1, 6-11 

item descriptions, 6-13 


return entry, 6-17 

return entry items, 6-18 

return entry structure definition 

element, 6-17 



(ACQ_ELT_INFO) item descriptions 

ABS_SUBTYPE, 6-14 

ABS_TYPE, 6-13 

CHAR_TYPE, 6-14 

DELETION, 6-16 

ELT_NAME, 6-13 

ELT_VERSION, 6-13 

INFO_DETAIL, 6-16 

MAX_DATE_TIME, 6-15 

MAX_SEQ_NUM, 6-15 

MAX_SIZE, 6-15 

MIN_DATE_TIME, 6-14 

MIN_SEQ_NUM, 6-15 

MIN_SIZE, 6-15 

NUM_SELECTED, 6-16 

OMN_SYM_SUBTYPE, 6-14 

OMN_TYPE, 6-13 

REL_TYPE, 6-13 

SYM_TYPE, 6-13 


(ACQ_ELT_INFO) return entry items 


ELT_TYPE, 6-19 


if ELT_TYPE = ABS, 6-21 

if ELT_TYPE = OMN, 6-22 

if ELT_TYPE = REL, 6-22 

if ELT_TYPE = SYM, 6-23 

if INFO_DETAIL = LONG, 6-20 


RESULT_INDICATOR, 6-18 

SEQ_NUM, 6-19 

acquire file information function 

(ACQ_FILE_INFO) 

C language return entry items, 3-6 

COBOL return entry items, 3-34 

defined, 3-1 

FORTRAN return entry items, 3-34 


7830 9796–013 Index–1

Index 




(ACQ_FILE_INFO) C language return 

entry items 

cataloged-file part, 3-11 

mass storage part, 3-15 

nonfloating part, 3-6 

run-assignment part, 3-27 

security part, 3-25 

tape part, 3-19 

volume part, 3-26 


(ACQ_FILE_INFO) COBOL return 

entry items 

CAT_INFO_PRESENT, 3-34 

EXTENDED_INFO_PRESENT, 3-34 

MASS_STORAGE_INFO_PRESENT, 3-34 

RUN_ASG_INFO_PRESENT, 3-35 

SECURITY_INFO_PRESENT, 3-34 

TAPE_INFO_PRESENT, 3-34 

VOL_INFO_PRESENT, 3-35 


(ACQ_FILE_INFO) FORTRAN return 

entry items 

CAT_INFO_PRESENT, 3-34 

EXTENDED_INFO_PRESENT, 3-34 

MASS_STORAGE_INFO_PRESENT, 3-34 

RUN_ASG_INFO_PRESENT, 3-35 

SECURITY_INFO_PRESENT, 3-34 

TAPE_INFO_PRESENT, 3-34 

VOL_INFO_PRESENT, 3-35 


(ACQ_FILE_INFO) item descriptions 


RTN_RUN_ASG_INFO, 3-3 

RTN_SECURITY_INFO, 3-3 

RTN_VOL_INFO, 3-2 

RUN_EQUIP_MNEMONIC, 3-3 

acquire file list function (ACQ_FILE_LIST) 

defined, 3-36 




acquire file list function (ACQ_FILE_LIST) 

item descriptions 

ACCOUNT_ID, 3-43 

ARC_NAME, 3-43 

DIRECTORY_ID, 3-40 

EQUIP_TYPE, 3-45 

FILE_OWNER_USER_ID, 3-43 

FILENAME, 3-41 


LIFETIME, 3-40 

MAX_CAT_DATE_TIME, 3-44 

MAX_CLEARANCE_LEVEL, 3-44 

MAX_F_CYCLE, 3-42 

MAX_F_CYCLE_TYPE, 3-42 

MAX_LAST_REF_DATE_TIME, 3-44 

MIN_CAT_DATE_TIME, 3-44 

MIN_CLEARANCE_LEVEL, 3-43 

MIN_F_CYCLE, 3-42 

MIN_F-CYCLE-TYPE, 3-41 

MIN_LAST_REF_DATE_TIME, 3-44 


PACK_ID, 3-41 

PROJECT_ID, 3-43 

QUALIFIER, 3-41 

RTN_EQUIP_MNEMONIC, 3-40 

RTN_RUN_ASG_INFO, 3-39 

RTN_SECURITY, 3-39 

RTN_VOL_INFO, 3-39 

SEARCH_SET, 3-40 

SELECT_ON_SITE_INFO, 3-45 

SITE_INFO, 3-45 

acquire object module entry point 

defined, 6-1, 6-29 


options, 6-30 




element, 6-35 


acquire object module entry point item 

descriptions 



EP_NAME, 6-34 


MAX_COUNT, 6-32 

MAX_DATE_TIME, 6-33 

MIN_DATE_TIME, 6-33 


SCS_CONFORMANCE, 6-33 

TEXT_TYPE, 6-32 

acquire object module entry point return entry 

items 

CREATE_DATE_TIME, 6-36 

EP_INDEX, 6-35 

EP_NAME, 6-37 

EP_NAME_LENGTH, 6-37 

EP_TYPE, 6-36 

long form items, 6-37 

PREPPED, 6-37 

SEQ_NUM, 6-35 

Index–2 7830 9796–013


VISIBILITY, 6-36 

acquire procedure information function 

(ACQ_PROC_INFO) 

COBOL return entry items, 6-45 

COBOL structure definition element, 6-44 

defined, 6-1, 6-39 


options, 6-39 




element, 6-43 



(ACQ_PROC_INFO) COBOL return 

entry items 

DELETE_FLAG, 6-45 



PROC_LOCATION, 6-46 

PROC_NAME, 6-46 

SEQ_NUM, 6-45 



(ACQ_PROC_INFO) item descriptions 






NUM_SELECTION, 6-42 


PROC_TABLE, 6-41 


(ACQ_PROC_INFO) return entry 

items 


if INFO_DETAIL = LONG, 6-44 

PROC_LOCATION, 6-44 


SEQ_NUM, 6-43 


acquire relocatable entry point 

defined, 6-1, 6-24 


options, 6-24 




acquire relocatable entry point item 

descriptions 


Index 



EP_NAME, 6-26 




acquire relocatable entry point return entry 

items 




EP_NAME, 6-28 

SEQ_NUM, 6-28 

7830 9796–013 Index–3 

B 

BUFFON, 3-22 

BUFOFF, 3-22 

BUFTAP, 3-22, 5-9, 5-29, 10-12 

C 

C programs 

constant name prefixes, 11-3 

general PCFP elements, 11-1 

handling errors, 11-9 

handling warnings, 11-9 

include element example, 11-2 

include element file, 11-1 

include element form, 11-1 

include element name, 11-1 

include element version, 11-1 

naming conventions, 11-2 

return entry requirements, 11-10 

calling PCFP 

examples, 1-3 

change element attributes function 

(CHG_ELT) 

defined, 8-1 


options, 8-2 


change element attributes function 

(CHG_ELT) item descriptions 


ABS_TYPE, 8-4 

CHANGE_DATE_TIME, 8-6 

CHANGE_SYM_SUBTYPE, 8-6 

ELT_NAME, 8-3 

ELT_VERSION, 8-4

Index 

EXCLUSIVE_ASSIGN, 8-6 


INFO_TO_RETURN, 8-8 

NEW_CYCLE_LIMIT, 8-7 

NEW_ELT_NAME, 8-5 

NEW_ELT_VERSION, 8-5 

NEW_OMN_SYM_SUBTYPE, 8-7 

NUM_FAILED, 8-9 


NUM_SUCCESSFUL, 8-9 


OMN_TYPE, 8-4 

PROCEED_ON_CONFLICT, 8-6 

REL_TYPE, 8-4 

SYM_TYPE, 8-4 

change file cycle attributes function 

(CHG_FILE_CYC) 

defined, 4-1, 4-7 


options, 4-7 



change file cycle attributes function 

(CHG_FILE_CYC) item descriptions 

ALLOW_DELETION, 4-8 

F_CYCLES_DELETED, 4-9 

F_CYCLES_RETAINED, 4-9 

MAX_F_CYCLES, 4-8 

change file keys function (CHG_FILE_KEY) 


READ_KEY, 4-14 

WRITE_KEY, 4-14 

change file keys function (CHG_FILE_KEYS) 

defined, 4-1, 4-13 



change file security attributes function 

(CHG_FILE_SEC) 

defined, 4-1, 4-10 




change file security attributes function 

(CHG_FILE_SEC) item descriptions 

ACR_NAME, 4-12 

CHG_CLEARANCE_LEVEL, 4-11 

CHG_FILE_OWNER, 4-11 

CLEARANCE_LEVEL, 4-11 

FILE_OWNER_USER_ID, 4-12 

PRIVACY, 4-12 

change file specific attributes function 

(CHG_FILE) 

defined, 4-1 



change file specific attributes function 

(CHG_FILE) item descriptions 

ACCOUNT_ID, 4-3 

BACKUP_DISABLE, 4-5 

CACHE_DISABLE, 4-5 

CHG_SITE_INFO, 4-6 

DIRECTORY_DISABLE, 4-4 

INIT_PROGRAM_FILE, 4-3 

PROJECT_ID, 4-3 

READ_ONLY, 4-5 

ROLLOUT_PROHIBITED, 4-3 

SITE_INFO, 4-6 

WRITE_DISABLE, 4-4 

WRITE_ONLY, 4-6 

changing file attributes, See change file 

function; change file keys function; 

change file specific 

character, defined, 2-3 

close SAF function (CLOSE_SAF) 

item description, FORMAT, 10-13 


COBOL reserved word 

DAY, 2-4 

PF, 12-4 

TAPE, 12-4 

comparing date-time values, 2-4 

condition, defined, 2-3 

copy element function (COPY_ELT) 

copying object modules, 7-2 

copying relocatable elements, 7-2 

defined, 7-1 


options, 7-1 

parameters, 7-1, 7-2 


copy element function (COPY_ELT) item 

descriptions 


ABS_TYPE, 7-4 

CYCLE_NUM, 7-8 

CYCLE_TYPE, 7-7 

DEST_ELT_NAME, 7-6 

DEST_ELT_VERSION, 7-6 

ELT_NAME, 7-4 





NEW_DATE_TIME, 7-6 



Index–4 7830 9796–013



OMN_TYPE, 7-4 

ON_CONFLICT, 7-7 

REL_TYPE, 7-4 

SYM_TYPE, 7-4 

copy omnibus element to RAF function 

(COPY_OMN_ELT_RAF) 

defined, 7-21 




copy omnibus element to RAF function 

(COPY_OMN_ELT_RAF) item 

descriptions 

AMOUNT_COPIED, 7-22 



PREVENT OVERCOPY, 7-22 

copy RAF to omnibus element function 

(COPY_RAF_OMN_ELT) 

defined, 7-23 


options, 7-23 



copy RAF to omnibus element function 

(COPY_RAF_OMN_ELT) item 

descriptions 


DEST_ELT_NAME, 7-24 


DEST_OMN_SUBTYPE, 7-25 



copy RAF to RAF function (COPY_RAF_RAF) 

defined, 5-1 


options, 5-1 



copy RAF to RAF function (COPY_RAF_RAF) 



PREVENT_OVERCOPY, 5-2 

STORAGE_TO_RELEASE, 5-3 

ZERO_RELEASED_STORAGE, 5-2 

copy RAF to SAF function (COPY_RAF_SAF) 

defined, 5-1, 5-4 


options, 5-4 


Index 




DEST_BLOCK_SIZE, 5-9 

DEST_FORMAT, 5-9 

OMIT_LOG_END_MARK, 5-8 

ON_END_OF_DEST_FILE, 5-10 

SAVE_CHECKSUMS, 5-8 

WRITE_OBSOLETE_VARIANT, 5-8 


return entry items 

ENTRY_SIZE, 5-12 

FRAGMENT_SIZE, 5-13 

LOGICAL_FILE_POSITION, 5-12 

NUM_VOLS, 5-12 


VOL_ID, 5-13 



copy RAF to symbolic element 

(COPY_RAF_SYM_ELT) 

defined, 7-17 


options, 7-17 



copy RAF to symbolic element 

(COPY_RAF_SYM_ELT) item 

descriptions 



DEST_SYM_ELT, 7-18 

DEST_SYM_SUBTYPE, 7-19 



copy SAF to RAF function (COPY_SAF_RAF) 

defined, 5-1, 5-14 


options, 5-14 







DESC_RTN_AREA_SIZE, 5-19 

LOC_FIRST_CHECKSUM_ERROR, 5-19 

LOC_FIRST_TRACK_SEQ_ERROR, 5-19 

NUM_CHECKSUM_ERRORS, 5-19 

NUM_DEST_FILES, 5-18 

NUM_TRACK_SEQ_ERRORS, 5-19 

ON_END_OF_SOURCE_FILE, 5-18 

PREVENT_OVERCOPY, 5-17 

7830 9796–013 Index–5

Index 

PROCESS_CHECKSUM_ERRORS, 5-17 

PROCESS_TRACK_SEQ_ERRORS, 5-17 





BLOCK_SIZE, 5-21 

DATE_TIME_COPIED, 5-22 

F_CYCLE, 5-23 

F_CYCLE_TYPE, 5-23 

FILENAME, 5-22 

FORMAT, 5-21 

HIGHEST_WORD_WRITTEN, 5-23 



VOL_ID, 5-21 

copy SAF to SAF function (COPY_SAF_SAF) 

defined, 5-1, 5-24 


options, 5-24 







DESC_RTN_AREA_SIZE, 5-30 

DEST_BLOCK_SIZE, 5-30 

LOC_FIRST_CHECKSUM_ERROR, 5-32 

LOC_FIRST_TRACK_SEQ_ERROR, 5-32 

NUM_CHECKSUM_ERRORS, 5-31 

NUM_DEST_FILES, 5-29 

NUM_TRACK_SEQ_ERRORS, 5-32 

OMIT_LOG_END_MARK, 5-28 

ON_END_OF_DEST_FILE, 5-31 

ON_END_OF_SOURCE_FILE, 5-30 

PROCESS_CHECKSUM_ERRORS, 5-28 

PROCESS_TRACK_SEQ_ERRORS, 5-28 

SAVE_CHECKSUMS, 5-29 

WRITE_OBSOLETE_VARIANT, 5-29 



ENTRY_SIZE, 5-12 

FRAGMENT_SIZE, 5-13 


NUM_VOLS, 5-12 


VOL_ID, 5-13 

copy symbolic element to RAF 

(COPY_SYM_ELT_RAF) 

defined, 7-14 


options, 7-14 



copy symbolic element to RAF 

(COPY_SYM_ELT_RAF) item 

descriptions 

ACTION, 7-15 


CYCLE_NUM, 7-16 

CYCLE_TYPE, 7-16 



create program file entry point table function 

(PREP_PF) 

defined, 8-36 


options, 8-36 



create program file entry point table function 

(PREP_PF) item descriptions 

DUP_REL_EP_CNT, 8-38 

EP_TYPE, 8-37 

OM_EP_CNT, 8-38 

OVERWRITE_OLD_EP_TABLE, 8-37 

REL_EP_CNT, 8-37 

Index–6 7830 9796–013 

D 

data type definitions 

character, 2-3 

condition, 2-3 

date-time, 2-4 

integer, 2-3 

value-list, 2-4 

date-time, defined, 2-4 

DAY, COBOL reserved word, 2-4 

delete elements function (DELETE_ELT) 

defined, 8-10 


options, 8-10 



delete elements function (DELETE_ELT) item 

descriptions 



ALL_INFO, 8-13 




INFO_DETAIL, 8-14







delete file function (DELETE_FILE) 

defined, 9-4 


options, 9-4 



delete file function (DELETE_FILE) item 

descriptions 



deleting a file, See delete file function 

directory-id, unique file identifier, 2-4 

E 

EOF mark, 5-24 

erase RAF function (ERASE_RAF) 

defined, 9-1 


options, 9-1 



erase RAF function (ERASE_RAF) item 

descriptions 

STORAGE_RELEASED, 9-3 



ZERO_RETAINED_STORAGE, 9-3 

erasing files, See erase RAF function 

examples 

ACQ_ELT_INFO, 1-14 

C calling PCFP functions, 11-15, 11-16, 

11-17 

calling PCFP, 1-3 

COBOL calling PCFP functions, 12-10, 

12-11, 12-14 

COPY_RAF_RAF, 1-9 

declaring a return area, 11-11 

DELETE_FILE, 1-3 

FORTRAN calling PCFP functions, 13-11, 

13-12 

handling date-time items, 11-10, 12-7 

setting items in a bit array, 11-9 

using MOVE statement with PCFP, 12-6 

examples handling date-time items 

C, 11-10 

COBOL, 12-7 

Index 

7830 9796–013 Index–7 

F 

fast tape access, 5-13, 5-22, 10-1, 10-5, 

10-10, 10-14 

F-cycle, unique file identifier, 2-4 

file identifier 

defined, 2-2 

structure defined, 2-5 

file identifier packet 


file identifier packet item descriptions 

DIRECTORY_ID, 2-6 

F_CYCLE, 2-7 

F_CYCLE_TYPE, 2-7 

FILENAME, 2-6 

INTERFACE_LEVEL, 2-6 


READ_KEY, 2-7 

WRITE_KEY, 2-7 

file identity 

initialization of, 2-5 

items for uniqueness, 2-4 

unique identifier 

directory-id, 2-4 

F-cycle, 2-4 

F-cycle type, 2-4 

file name, 2-4 

interface level number, 2-4 

qualifier, 2-4 

read/write keys, 2-4 

file information, See acquire file information 

function; acquire file list function 

file name, unique file identifier, 2-4 

file types, 1-2 

FORTRAN examples, 13-9 

FORTRAN program examples 

copying a file, 13-11 

deleting a file, 13-10 

FORTRAN programs 

compiling with PCFP, 13-9 

function names, 13-4 

handling errors, 13-9 

handling warnings, 13-9 

item names within packets, 13-4 

naming conventions, 13-4 

packet names, 13-4 

PCFP constants defined, 13-4

Index 

procedure descriptions, 13-1 

procedure file, 13-1 

procedure names, 13-1 

function packet 

defined, 2-2 

return-information part item 

descriptions, 2-13 

function packet generic part item descriptions 

AUX_ERROR_CODE, 2-12 

ERROR_CLASS, 2-11 

ERROR_FILE, 2-11 

GEN_DATE_TIME, 2-10 

NULL_TERM_STRINGS, 2-10 

QUESTION_MARK_MATCHES_SPACE, 2- 

10 

SOFTWARE_LEVEL, 2-10 

WAIT_ON_FACILITIES, 2-10 

WORK_AREA_SIZE, 2-10 

function packet return-information part item 

descriptions 

NUM_RTN_ENTRIES, 2-13 

NUMB_ENTRIES_IN_RTN_AREA, 2-14 

RTN_AREA-SIZE, 2-13 

RTN_ENTRY-SIZE, 2-14 

function parameters 

file identifier, 2-2 

function packet, 2-2 

return area, 2-2 

work area, 2-2 

functions 

aspects of, 2-16 

file identification, 2-4 

general form of, 2-1 

parameters used by most functions, 2-1, 

2-2 

successful completion of, 2-2 

value returned, 2-2 

G 

generation date and time, PCFP 

processor, 1-23 

I 

integer, defined, 2-3 

item descriptions, See data type definitions 

Index–8 7830 9796–013 

L 

level, PCFP processor, 1-23 

M 

move SAF function (MOVE_SAF) 

defined, 10-1 


options, 10-1 



move SAF function (MOVE_SAF) item 

descriptions 

CURRENT_VOL_ONLY, 10-4 

INTERLOCK, 10-4 


MOVE_NUM, 10-6 

NUM_FILES_MOVED, 10-6 

ON_END_OF_FILE, 10-6 

POSITION_AT_END_OF_LOG_FILE, 10-4 

TYPE_OF_MOVE, 10-5 

VOL_ID, 10-7 

O 

object module entry point table 

option not specified, 8-36 

removal of object module, 8-10 

removal of relocatable, 8-2 

P 

pack program file function (PAK_PF) 



pack program file function (PAK_PF) item 

descriptions 

COBOL_PROC_NUM_ENTRIES, 8-29 

COBOL_PROC_OPEN_ENTRIES, 8-29 

DEAD_SPACE, 8-30 

ELT_NUM_ENTRIES, 8-28 

ELT_OPEN_ENTRIES, 8-28 

FTN_PLS_PROC_NUM_ENTRIES, 8-29 

FTN_PLS_PROC_OPEN_ENTRIES, 8-29 

LATEST_ABS_SEQ_NUM, 8-28 

MASM_PROC_NUM_ENTRIES, 8-29 

MASM_PROC_OPEN_ENTRIES, 8-29

NEXT_TEXT_LOCATION, 8-28 

NUM_ABS_ELTS, 8-30 

NUM_DELETED_ELTS, 8-30 

NUM_OMN_ELTS, 8-30 

NUM_REL_ELTS, 8-30 

NUM_SYM_ELTS, 8-30 

REL_EP_NUM_ENTRIES, 8-29 

REL_EP_OPEN_ENTRIES, 8-30 


TEXT_SIZE, 8-28 

TOC_SIZE, 8-28 


PCFP 

acquire element information example, 1-14 

copy example, 1-9 

DELETE_FILE example, 1-3 

design, 1-1 

file types, 1-2 

function parameters, 2-2 

processor generation date and time, 1-23 

processor level, 1-23 

PF, COBOL reserved word, 12-4 

positioning tape files, See move SAF 

function 

programming languages 

C examples, 11-14 

COBOL examples, 12-9 

special considerations for, 2-1 

Q 

qualifier, unique file identifier, 2-4 

R 

return area, defined, 2-2 

S 

SYNCHRONIZE, 5-9, 5-29, 10-14 

T 

TAPE, COBOL reserved word, 12-4 

Index 

7830 9796–013 Index–9 

U 

undelete elements function (UNDELETE_ELT) 

defined, 8-15 

options, 8-16 

undelete elements function (UNDELETE_ELT) 


ABS_SUBTYPE array (0 

17), 8-19 


ALLOW_DELETION, 8-19 




FP_ERR_NONE, 8-22 

FP_INFO_PROC_TBL_ERR, 8-22 

FP_WARN_ELT_DELETE_NOT_ALLOWED 

, 8-22 

FP_WARN_ELT_REL_SEQ_NUM_ERR, 8-2 

2 

FP_WARN_ELT_UNDELETED, 8-22 






OMN_SYM_SUBTYPE array (0 

71), 8-18 



SEQ_NUM, 8-20 

SEQ_NUM_TYPE, 8-19 


updating program files, See change element 

attributes function; delete elements 

function; pack program file function; 

create program file entry point table 

function 

using a bit array, 12-7 

V 

value-list, defined, 2-4 

W 

wild-card characters 

defined, 2-15 

examples of use, 2-15 

work area, defined, 2-2, 2-14

Index 

Index–10 7830 9796–013

© 2008 Unisys Corporation. 

All rights reserved. 

*78309796-013* 

7830 9796–013

Programming Reference Manual - Public Support Login - Unisys

Create successful ePaper yourself

Delete template?

Save as template?