Programming Reference Manual - Public Support Login - Unisys
Programming Reference Manual - Public Support Login - Unisys
Programming Reference Manual - Public Support Login - Unisys
You also want an ePaper? Increase the reach of your titles
YUMPU automatically turns print PDFs into web optimized ePapers that Google loves.
OS 2200<br />
Program-Callable FURPUR (PCFP)<br />
<strong>Programming</strong> <strong>Reference</strong> <strong>Manual</strong><br />
ClearPath OS 2200 Release 11.3<br />
September 2008 7830 9796–013<br />
unisys<br />
imagine it. done.
NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THIS DOCUMENT. Any product or related information<br />
described herein is only furnished pursuant and subject to the terms and conditions of a duly executed agreement to<br />
purchase or lease equipment or to license software. The only warranties made by <strong>Unisys</strong>, if any, with respect to the<br />
products described in this document are set forth in such agreement. <strong>Unisys</strong> cannot accept any financial or other<br />
responsibility that may be the result of your use of the information in this document or software material, including<br />
direct, special, or consequential damages.<br />
You should be very careful to ensure that the use of this information and/or software material complies with the laws,<br />
rules, and regulations of the jurisdictions with respect to which it is used.<br />
The information contained herein is subject to change without notice. Revisions may be issued to advise of such<br />
changes and/or additions.<br />
Notice to U.S. Government End Users: This is commercial computer software or hardware documentation developed at<br />
private expense. Use, reproduction, or disclosure by the Government is subject to the terms of <strong>Unisys</strong> standard<br />
commercial license for the products, and where applicable, the restricted/limited rights provisions of the contract data<br />
rights clauses.<br />
<strong>Unisys</strong> and ClearPath are registered trademarks of <strong>Unisys</strong> Corporation in the United States and other countries.<br />
All other brands and products referenced in this document are acknowledged to be the trademarks or registered<br />
trademarks of their respective holders.
OS 2200<br />
Program-Callable FURPUR<br />
(PCFP)<br />
<strong>Programming</strong> <strong>Reference</strong><br />
<strong>Manual</strong><br />
ClearPath OS 2200<br />
Release 11.3<br />
OS 2200<br />
Program-Callable<br />
FURPUR (PCFP)<br />
<strong>Programming</strong><br />
<strong>Reference</strong><br />
<strong>Manual</strong><br />
ClearPath OS<br />
2200 Release<br />
11.3<br />
7830 9796–013 7830 9796–013<br />
Bend here, peel upwards and apply to spine.
Contents<br />
Section 1. Using PCFP<br />
1.1. Definition of PCFP .................................................................... 1–1<br />
1.2. File Types Operated on by PCFP ............................................. 1–2<br />
1.3. Calling PCFP Functions ............................................................ 1–3<br />
1.3.1. Calling PCFP to Delete a File ........................................... 1–3<br />
1.3.2. Calling PCFP to Copy a File ............................................. 1–9<br />
1.3.3. Calling PCFP to Acquire Element Information<br />
from a Program File .................................................. 1–14<br />
1.4. Summary of PCFP Functions ................................................. 1–21<br />
1.5. PCFP Processor ..................................................................... 1–23<br />
Section 2. Functions of PCFP<br />
2.1. Typical Form of PCFP Functions .............................................. 2–1<br />
2.2. Data Types ............................................................................... 2–3<br />
2.3. File Identifiers .......................................................................... 2–4<br />
2.4. Function Packet ....................................................................... 2–8<br />
2.4.1. Generic Part of the Function Packet ............................... 2–8<br />
2.4.2. Return-Information Part of the Function Packet ........... 2–13<br />
2.5. Work Area .............................................................................. 2–14<br />
2.6. Wild-Card Characters ............................................................. 2–15<br />
2.7. Function-Specific Interface Information ................................. 2–16<br />
2.8. Multi-Activity Programs .......................................................... 2–17<br />
Section 3. Acquiring General File Information<br />
3.1. Acquire File Information (ACQ_FILE_INFO) ............................. 3–1<br />
3.1.1. Parameters ...................................................................... 3–1<br />
3.1.2. Function Packet ............................................................... 3–1<br />
3.1.3. File Identifier .................................................................... 3–3<br />
3.1.4. Return Information (C Language) .................................... 3–4<br />
3.1.4.1. Nonfloating Part ...................................................... 3–5<br />
3.1.4.2. Cataloged File Part ................................................ 3–11<br />
3.1.4.3. Mass Storage Part ................................................ 3–15<br />
3.1.4.4. Tape Part............................................................... 3–18<br />
3.1.4.5. Security Part ......................................................... 3–24<br />
3.1.4.6. Volume Part .......................................................... 3–25<br />
3.1.4.7. Run Assignment Part ............................................ 3–27<br />
3.1.5. Return Information (COBOL and FORTRAN) ................ 3–28<br />
3.1.5.1. Short Form Return Information (COBOL<br />
and FORTRAN) ................................................. 3–29<br />
7830 9796–013 iii
Contents<br />
3.1.5.2. Long Form Return Information (COBOL and<br />
FORTRAN) ........................................................ 3–30<br />
3.1.6. Work Area ...................................................................... 3–35<br />
3.2. Acquire File List (ACQ_FILE_LIST) ......................................... 3–36<br />
3.2.1. Parameters ..................................................................... 3–36<br />
3.2.2. Function Packet ............................................................. 3–37<br />
3.2.3. Return Information ......................................................... 3–46<br />
3.2.4. Work Area ...................................................................... 3–47<br />
Section 4. Changing File Attributes<br />
4.1. Change File Specific Attributes (CHG_FILE) ............................. 4–1<br />
4.1.1. Parameters ....................................................................... 4–2<br />
4.1.2. Function Packet ............................................................... 4–2<br />
4.1.3. File Identifier .................................................................... 4–7<br />
4.1.4. Work Area ........................................................................ 4–7<br />
4.2. Change File Cycle Attributes (CHG_FILE_CYC) ........................ 4–7<br />
4.2.1. Parameters ....................................................................... 4–8<br />
4.2.2. Function Packet ............................................................... 4–8<br />
4.2.3. File Identifier .................................................................... 4–9<br />
4.2.4. Work Area ........................................................................ 4–9<br />
4.3. Change File Security Attributes (CHG_FILE_SEC) .................. 4–10<br />
4.3.1. Parameters ..................................................................... 4–10<br />
4.3.2. Function Packet ............................................................. 4–11<br />
4.3.3. File Identifier .................................................................. 4–12<br />
4.3.4. Work Area ...................................................................... 4–12<br />
4.4. Change File Keys (CHG_FILE_KEYS) ...................................... 4–13<br />
4.4.1. Parameters ..................................................................... 4–13<br />
4.4.2. Function Packet ............................................................. 4–13<br />
4.4.3. File Identifier .................................................................. 4–14<br />
4.4.4. Work Area ...................................................................... 4–14<br />
4.5. Change File Name (CHG_FILE_NAME) .................................. 4–15<br />
4.5.1. Parameters ..................................................................... 4–15<br />
4.5.2. Function Packet ............................................................. 4–16<br />
4.5.3. File Identifier .................................................................. 4–17<br />
4.5.4. Work Area ...................................................................... 4–17<br />
Section 5. Copying Between Files<br />
5.1. Copy RAF to RAF (COPY_RAF_RAF) ........................................ 5–1<br />
5.1.1. Parameters ....................................................................... 5–2<br />
5.1.2. Function Packet ............................................................... 5–2<br />
5.1.3. Source File Identifier ........................................................ 5–3<br />
5.1.4. Destination File Identifier ................................................. 5–3<br />
5.1.5. Work Area ........................................................................ 5–3<br />
5.2. Copy RAF to SAF (COPY_RAF_SAF) ........................................ 5–4<br />
5.2.1. Parameters ....................................................................... 5–6<br />
5.2.2. Function Packet ............................................................... 5–7<br />
5.2.3. Source File Identifier ...................................................... 5–10<br />
5.2.4. Destination File Identifier ............................................... 5–10<br />
5.2.5. User Descriptor Data ..................................................... 5–10<br />
iv 7830 9796–013
Contents<br />
5.2.6. Return Entry .................................................................. 5–11<br />
5.2.7. Work Area ..................................................................... 5–13<br />
5.3. Copy SAF to RAF (COPY_SAF_RAF) ..................................... 5–14<br />
5.3.1. Parameters .................................................................... 5–16<br />
5.3.2. Function Packet ............................................................. 5–16<br />
5.3.3. Source File Identifier ..................................................... 5–20<br />
5.3.4. Destination File Identifier .............................................. 5–20<br />
5.3.5. Descriptor Return Area ................................................. 5–20<br />
5.3.6. Work Area ..................................................................... 5–23<br />
5.4. Copy SAF to SAF (COPY_SAF_SAF) ...................................... 5–24<br />
5.4.1. Parameters .................................................................... 5–26<br />
5.4.2. Function Packet ............................................................. 5–27<br />
5.4.3. Source File Identifier ..................................................... 5–32<br />
5.4.4. Destination File Identifier .............................................. 5–32<br />
5.4.5. User Descriptor Data ..................................................... 5–32<br />
5.4.6. Return Entry .................................................................. 5–32<br />
5.4.7. Descriptor Return Area ................................................. 5–33<br />
5.4.8. Work Area ..................................................................... 5–33<br />
Section 6. Acquiring Program File Information<br />
6.1. Acquire Basic Program File Information<br />
(ACQ_BASIC_PF_INFO) ....................................................... 6–1<br />
6.1.1. Parameters ...................................................................... 6–2<br />
6.1.2. Function Packet ............................................................... 6–3<br />
6.1.3. File Identifier .................................................................. 6–10<br />
6.1.4. Work Area ..................................................................... 6–10<br />
6.2. Acquire Element Information (ACQ_ELT_INFO) .................... 6–11<br />
6.2.1. Parameters .................................................................... 6–11<br />
6.2.2. Function Packet ............................................................. 6–12<br />
6.2.3. File Identifier .................................................................. 6–17<br />
6.2.4. Return Entry .................................................................. 6–17<br />
6.2.5. Work Area ..................................................................... 6–23<br />
6.3. Acquire Relocatable Entry Point Information<br />
(ACQ_REL_EP_INFO) ........................................................ 6–24<br />
6.3.1. Parameters .................................................................... 6–24<br />
6.3.2. Function Packet ............................................................. 6–25<br />
6.3.3. File Identifier .................................................................. 6–27<br />
6.3.4. Return Entry .................................................................. 6–27<br />
6.3.5. Work Area ..................................................................... 6–28<br />
6.4. Acquire Object Module Entry Point Information<br />
(ACQ_OM_EP_INFO) ......................................................... 6–29<br />
6.4.1. Parameters .................................................................... 6–30<br />
6.4.2. Function Packet ............................................................. 6–31<br />
6.4.3. File Identifier .................................................................. 6–34<br />
6.4.4. Return Entry .................................................................. 6–35<br />
6.4.5. Work Area ..................................................................... 6–38<br />
6.5. Acquire Procedure Information (ACQ_PROC_INFO) ............. 6–39<br />
6.5.1. Parameters .................................................................... 6–39<br />
6.5.2. Function Packet ............................................................. 6–40<br />
6.5.3. File Identifier .................................................................. 6–42<br />
7830 9796–013 v
Contents<br />
6.5.4. Return Entry for MASM, FORTRAN, and PLUS<br />
Procedures ................................................................. 6–42<br />
6.5.5. Return Entry for COBOL Procedures ............................. 6–44<br />
6.5.6. Work Area ...................................................................... 6–46<br />
Section 7. Copying Program File Elements<br />
7.1. Copy Elements (COPY_ELT) ..................................................... 7–1<br />
7.1.1. Parameters ....................................................................... 7–2<br />
7.1.2. Function Packet ............................................................... 7–3<br />
7.1.3. Source File Identifier ...................................................... 7–10<br />
7.1.4. Destination File Identifier ............................................... 7–10<br />
7.1.5. Return Entry ................................................................... 7–10<br />
7.1.6. Work Area ...................................................................... 7–13<br />
7.2. Copy Symbolic Element to RAF<br />
(COPY_SYM_ELT_RAF)...................................................... 7–14<br />
7.2.1. Parameters ..................................................................... 7–14<br />
7.2.2. Function Packet ............................................................. 7–15<br />
7.2.3. Source File Identifier ...................................................... 7–16<br />
7.2.4. Destination File Identifier ............................................... 7–17<br />
7.2.5. Work Area ...................................................................... 7–17<br />
7.3. Copy RAF to Symbolic Element<br />
(COPY_RAF_SYM_ELT)...................................................... 7–17<br />
7.3.1. Parameters ..................................................................... 7–17<br />
7.3.2. Function Packet ............................................................. 7–18<br />
7.3.3. Source File Identifier ...................................................... 7–20<br />
7.3.4. Destination File Identifier ............................................... 7–20<br />
7.3.5. Work Area ...................................................................... 7–20<br />
7.4. Copy Omnibus Element to RAF<br />
(COPY_OMN_ELT_RAF)..................................................... 7–21<br />
7.4.1. Parameters ..................................................................... 7–21<br />
7.4.2. Function Packet ............................................................. 7–21<br />
7.4.3. Source File Identifier ...................................................... 7–22<br />
7.4.4. Destination File Identifier ............................................... 7–22<br />
7.4.5. Work Area ...................................................................... 7–23<br />
7.5. Copy RAF to Omnibus Element<br />
(COPY_RAF_OMN_ELT)..................................................... 7–23<br />
7.5.1. Parameters ..................................................................... 7–23<br />
7.5.2. Function Packet ............................................................. 7–24<br />
7.5.3. Source File Identifier ...................................................... 7–26<br />
7.5.4. Destination File Identifier ............................................... 7–26<br />
7.5.5. Work Area ...................................................................... 7–26<br />
Section 8. Updating Program Files<br />
8.1. Change Element Attributes (CHG_ELT) ................................... 8–1<br />
8.1.1. Parameters ....................................................................... 8–2<br />
8.1.2. Function Packet ............................................................... 8–3<br />
8.1.3. File Identifier .................................................................... 8–9<br />
8.1.4. Return Entry ..................................................................... 8–9<br />
8.1.5. Work Area ...................................................................... 8–10<br />
vi 7830 9796–013
Contents<br />
8.2. Delete Elements (DELETE_ELT) ............................................ 8–10<br />
8.2.1. Parameters .................................................................... 8–11<br />
8.2.2. Function Packet ............................................................. 8–11<br />
8.2.3. File Identifier .................................................................. 8–14<br />
8.2.4. Return Entry .................................................................. 8–14<br />
8.2.5. Work Area ..................................................................... 8–14<br />
8.3. Undelete Elements (UNDELETE_ELT) ................................... 8–15<br />
8.3.1. Parameters .................................................................... 8–16<br />
8.3.2. Function Packet ............................................................. 8–17<br />
8.3.3. File Identifier .................................................................. 8–22<br />
8.3.4. Return Entry .................................................................. 8–22<br />
8.3.5. Work Area ..................................................................... 8–23<br />
8.4. Pack Program File (PACK_PF) ................................................ 8–24<br />
8.4.1. Parameters .................................................................... 8–25<br />
8.4.2. Function Packet ............................................................. 8–26<br />
8.4.3. File Identifier .................................................................. 8–31<br />
8.4.4. Work Area ..................................................................... 8–31<br />
8.4.4.1. Standard Method Work Area Requirements ........ 8–31<br />
8.4.4.2. Copy Method Work Area Requirements .............. 8–33<br />
8.5. Create Program File Entry Point Table (PREP_PF) ................. 8–36<br />
8.5.1. Parameters .................................................................... 8–36<br />
8.5.2. Function Packet ............................................................. 8–37<br />
8.5.3. File Identifier .................................................................. 8–38<br />
8.5.4. Work Area ..................................................................... 8–39<br />
Section 9. Erasing and Deleting Files<br />
9.1. Erase RAF (ERASE_RAF) ......................................................... 9–1<br />
9.1.1. Parameters ...................................................................... 9–2<br />
9.1.2. Function Packet ............................................................... 9–2<br />
9.1.3. File Identifier .................................................................... 9–4<br />
9.1.4. Work Area ....................................................................... 9–4<br />
9.2. Delete File (DELETE_FILE)....................................................... 9–4<br />
9.2.1. Parameters ...................................................................... 9–4<br />
9.2.2. Function Packet ............................................................... 9–5<br />
9.2.3. File Identifier .................................................................... 9–5<br />
9.2.4. Work Area ....................................................................... 9–5<br />
Section 10. Positioning and Closing Tape Files<br />
10.1. Move SAF (MOVE_SAF) ........................................................ 10–1<br />
10.1.1. Parameters .................................................................... 10–2<br />
10.1.2. Function Packet ............................................................. 10–3<br />
10.1.3. Actions Performed by the MOVE_SAF Function .......... 10–9<br />
10.1.4. File Identifier ................................................................ 10–10<br />
10.1.5. Work Area ................................................................... 10–10<br />
10.1.6. Fast Tape Access Considerations ............................... 10–10<br />
10.2. Close SAF (CLOSE_SAF) ..................................................... 10–12<br />
10.2.1. Parameters .................................................................. 10–13<br />
10.2.2. Function Packet ........................................................... 10–13<br />
7830 9796–013 vii
Contents<br />
10.2.3. File Identifier ................................................................ 10–14<br />
10.2.4. Work Area .................................................................... 10–14<br />
Section 11. Using PCFP with C<br />
11.1. Include Considerations ........................................................... 11–1<br />
11.2. Naming Conventions .............................................................. 11–2<br />
11.2.1. Function Names ............................................................. 11–3<br />
11.2.2. Typedef Names .............................................................. 11–3<br />
11.2.3. Item Names ................................................................... 11–3<br />
11.2.4. Names of Constants ...................................................... 11–3<br />
11.3. PCFP Data Types .................................................................... 11–4<br />
11.3.1. Structure Declarations ................................................... 11–5<br />
11.3.2. Implementing Generic Data Types ................................ 11–5<br />
11.4. Operating Rules and Coding Sequences ................................ 11–6<br />
11.4.1. Parameter Definitions .................................................... 11–6<br />
11.4.2. Initializing Input Parameters ........................................... 11–7<br />
11.4.3. Assigning Values to Character Strings Within<br />
Structures .................................................................. 11–7<br />
11.4.4. Work Area Parameter .................................................... 11–8<br />
11.4.5. Calling PCFP ................................................................... 11–8<br />
11.4.6. Handling Error Conditions .............................................. 11–9<br />
11.4.7. Items in a Bit Array ........................................................ 11–9<br />
11.4.8. Date-Time Items .......................................................... 11–10<br />
11.4.9. Return Area .................................................................. 11–10<br />
11.4.9.1. General Considerations ....................................... 11–10<br />
11.4.9.2. Special Considerations for _fp_acq_file_info<br />
and _fp_acq_file_list ........................................ 11–13<br />
11.5. Compiling and Linking Programs That Use PCFP ................. 11–14<br />
11.6. <strong>Programming</strong> Examples ....................................................... 11–14<br />
11.6.1. Calling PCFP to Delete a File ....................................... 11–15<br />
11.6.2. Calling PCFP to Copy a File .......................................... 11–16<br />
11.6.3. Calling PCFP to Acquire Element Information<br />
from a Program File ................................................. 11–17<br />
Section 12. Using PCFP with COBOL<br />
12.1. Copy Considerations ............................................................... 12–1<br />
12.2. Naming Conventions .............................................................. 12–3<br />
12.2.1. Subroutine Names ......................................................... 12–3<br />
12.2.2. Item Names ................................................................... 12–3<br />
12.2.3. Names of Constants ...................................................... 12–4<br />
12.3. PCFP Data Types .................................................................... 12–4<br />
12.3.1. Record Definitions ......................................................... 12–5<br />
12.3.2. Implementing Generic Data Types ................................ 12–5<br />
12.4. Operating Rules and Coding Sequences ................................ 12–6<br />
12.4.1. Initializing Input Parameters ........................................... 12–6<br />
12.4.2. Work Area Specification ................................................. 12–6<br />
12.4.3. Setting Items in a Bit Array ............................................ 12–7<br />
12.4.4. Handling Date-Time Items ............................................. 12–7<br />
12.4.5. Handling Error Conditions .............................................. 12–8<br />
viii 7830 9796–013
Contents<br />
12.4.6. Handling the Return Area Parameter ............................ 12–8<br />
12.5. Compiling and Linking Programs That Use PCFP .................. 12–9<br />
12.6. <strong>Programming</strong> Examples ......................................................... 12–9<br />
12.6.1. Calling PCFP to Delete a File ....................................... 12–10<br />
12.6.2. Calling PCFP to Copy a File ......................................... 12–11<br />
12.6.3. Calling PCFP to Acquire Element Information<br />
from a Program File ................................................ 12–14<br />
Section 13. Using PCFP with FORTRAN<br />
13.1. INCLUDE Element/Procedure Considerations ....................... 13–1<br />
13.2. Naming Conventions .............................................................. 13–3<br />
13.2.1. Function Names ............................................................ 13–3<br />
13.2.2. Packet Names ............................................................... 13–4<br />
13.2.3. Item Names Within Packets ......................................... 13–4<br />
13.2.4. Names of Constants...................................................... 13–4<br />
13.3. Form of Packet Definitions .................................................... 13–4<br />
13.4. Operating Rules and Coding Sequences ............................... 13–6<br />
13.4.1. Specifying Items Within Packets .................................. 13–6<br />
13.4.2. Handling Repeating Return Information ........................ 13–6<br />
13.4.3. Specifying Work Area .................................................... 13–7<br />
13.4.4. Initializing Input Parameters .......................................... 13–7<br />
13.4.5. Handling Date-Time Items ............................................ 13–8<br />
13.4.6. Calling PCFP .................................................................. 13–8<br />
13.4.7. Handling Error Conditions ............................................. 13–9<br />
13.5. Compiling and Linking Programs That Use PCFP .................. 13–9<br />
13.6. <strong>Programming</strong> Examples ......................................................... 13–9<br />
13.6.1. Calling PCFP to Delete a File ....................................... 13–10<br />
13.6.2. Calling PCFP to Copy a File ......................................... 13–11<br />
13.6.3. Calling PCFP to Acquire Element Information<br />
from a Program File ................................................ 13–12<br />
Appendix A. Error Messages<br />
A.1. Warnings and Informational Messages ................................... A–2<br />
A.2. Errors ........................................................................................ A–4<br />
A.2.1. Calling Program Errors .................................................... A–5<br />
A.2.2. Execution I/O Errors ...................................................... A–21<br />
A.2.3. Execution Errors Other than I/O Errors—All File<br />
Types......................................................................... A–23<br />
A.2.4. Execution Errors Other than I/O Errors—<br />
Sequential-Access Files ............................................ A–29<br />
A.2.5. Execution Errors Other than I/O Errors—<br />
Random-Access Files................................................ A–33<br />
A.2.6. Execution Errors Other than I/O Errors—Program<br />
Files ........................................................................... A–37<br />
A.2.7. Errors Associated with Assigning and Freeing<br />
Files ........................................................................... A–42<br />
A.2.8. Errors Associated with the PACK_PF Function ............. A–45<br />
7830 9796–013 ix
Contents<br />
Appendix B. Summary of FURPUR Commands<br />
Appendix C. PACK_PF Operation and Performance<br />
C.1. Standard Method Performance ............................................... C–1<br />
C.2. Copy Method Performance ..................................................... C–4<br />
C.3. Performance Comparison ........................................................ C–6<br />
C.4. File Contents in Error Cases .................................................... C–7<br />
Glossary ............................................................................................. 1<br />
Index ............................................................................................. 1<br />
x 7830 9796–013
Figures<br />
1–1. Calling the DELETE_FILE Function .................................................................... 1–4<br />
1–2. DELETE_FILE Function Packet Items ................................................................ 1–5<br />
1–3. DELETE_FILE Function Packet with Numeric Equivalents ................................ 1–6<br />
1–4. File Identifier Packet Items ................................................................................ 1–7<br />
1–5. File Identifier Packet Items with Numeric Equivalents ...................................... 1–8<br />
1–6. Calling the COPY_RAF_RAF Function................................................................ 1–9<br />
1–7. COPY_RAF_RAF Function Packet Items ......................................................... 1–10<br />
1–8. COPY_RAF_RAF Function Packet with Numeric Equivalents ......................... 1–11<br />
1–9. Source File Identifier Packet Items .................................................................. 1–12<br />
1–10. Source File Identifier Packet Items with Numeric Equivalents ........................ 1–12<br />
1–11. Calling the ACQ_ELT_INFO Function .............................................................. 1–14<br />
1–12. ACQ_ELT_INFO Function Packet Items (cont.) ............................................... 1–16<br />
1–12. ACQ_ELT_INFO Function Packet Items .......................................................... 1–17<br />
1–13. ACQ_ELT_INFO Function Packet Items with Numeric Equivalents<br />
(cont.) ........................................................................................................... 1–18<br />
1–13. ACQ_ELT_INFO Function Packet Items with Numeric Equivalents ................ 1–19<br />
2–1. File Identifier Packet Items ................................................................................ 2–5<br />
2–2. Generic Part of the Function Packet .................................................................. 2–9<br />
2–3. Return-Information Part of the Function Packet .............................................. 2–13<br />
3–1. ACQ_FILE_INFO Function Packet Items ........................................................... 3–2<br />
3–2. Nonfloating Part of the Return Entry for C Language ........................................ 3–5<br />
3–3. Cataloged File Part of the Return Entry for C Language .................................. 3–11<br />
3–4. Mass Storage Part of the Return Entry for C Language .................................. 3–15<br />
3–5. Tape Part of the Return Entry for C Language ................................................. 3–19<br />
3–6. Security Part of Return Entry for C Language .................................................. 3–24<br />
3–7. Volume Part of the Return Entry for C Language ............................................ 3–26<br />
3–8. Run Assignment Part of the Return Entry for C Language .............................. 3–27<br />
3–9. Mass Storage Part of the Return Entry for COBOL and FORTRAN<br />
Short Form ................................................................................................... 3–29<br />
3–10. Long Form Return Entry for Mass Storage File for COBOL and<br />
FORTRAN (cont.) ......................................................................................... 3–30<br />
3-10. Long Form Return Entry for Mass Storage File for COBOL and<br />
FORTRAN (cont.) ......................................................................................... 3–31<br />
3–10. Long Form Return Entry for Mass Storage File for COBOL and<br />
FORTRAN .................................................................................................... 3–32<br />
3–11. Long Form Tape Part of the Return Entry for COBOL and FORTRAN ............ 3–33<br />
3–12. ACQ_FILE_LIST Function Packet Items (cont.) ............................................... 3–37<br />
3–12. ACQ_FILE_LIST Function Packet Items .......................................................... 3–38<br />
4–1. CHG_FILE Function Packet Items ...................................................................... 4–2<br />
7830 9796–013 xi
Figures<br />
4–2. CHG_FILE_CYC Function Packet Items ............................................................. 4–8<br />
4–3. CHG_FILE_SEC Function Packet Items ............................................................ 4–11<br />
4–4. CHG_FILE_KEYS Function Packet Items .......................................................... 4–13<br />
4–5. CHG_FILE_NAME Function Packet Items ........................................................ 4–16<br />
5–1. COPY_RAF_RAF Function Packet Items ............................................................ 5–2<br />
5–2. COPY_RAF_SAF Function Packet Items ............................................................ 5–7<br />
5–3. COPY_RAF_SAF and COPY_SAF_SAF Return Entry Items ............................. 5–12<br />
5–4. COPY_SAF_RAF Function Packet Items .......................................................... 5–16<br />
5–5. Descriptor Return Area for COPY_SAF_RAF and COPY_SAF_SAF ................. 5–21<br />
5–6. COPY_SAF_SAF Function Packet and Return Area Items ............................... 5–27<br />
6–1. ACQ_BASIC_PF_INFO Function Packet Items ................................................... 6–3<br />
6–2. ACQ_ELT_INFO Function Packet Items ........................................................... 6–12<br />
6–3. The First 14 Words of the Return Entry ........................................................... 6–17<br />
6–4. ACQ_REL_EP_INFO Function Packet Items .................................................... 6–25<br />
6–5. ACQ_REL_EP_INFO Return Entry Items .......................................................... 6–27<br />
6–6. ACQ_OM_EP_INFO Function Packet Items ..................................................... 6–31<br />
6–7. ACQ_OM_EP_INFO Return Entry Items .......................................................... 6–35<br />
6–8. ACQ_PROC_INFO Function Packet Items ....................................................... 6–40<br />
6–9. ACQ_PROC_INFO Return Entry Structure When<br />
PROC_TABLE = MASM_PROC or FTN_PLS_PROC.................................... 6–43<br />
6–10. ACQ_PROC_INFO Return Information Structure When<br />
PROC_TABLE = COBOL PROC ................................................................... 6–45<br />
7–1. COPY_ELT Function Packet Items ..................................................................... 7–3<br />
7–2. Summary Return Entry ..................................................................................... 7–11<br />
7–3. COPY_SYM_ELT_RAF Function Packet Items ................................................. 7–15<br />
7–4. COPY_RAF_SYM_ELT Function Packet Items ................................................. 7–18<br />
7–5. COPY_OMN_ELT_RAF Function Packet Items ................................................ 7–21<br />
7–6. COPY_RAF_OMN_ELT Function Packet Items ................................................ 7–24<br />
8–1. CHG_ELT Function Packet Items ....................................................................... 8–3<br />
8–2. DELETE_ELT Function Packet Items ................................................................ 8–11<br />
8–3. UNDELETE_ELT Function Packet Items .......................................................... 8–17<br />
8–4. PACK_PF Function Packet Items ...................................................................... 8–26<br />
8–5. PREP_PF Function Packet Items ...................................................................... 8–37<br />
9–1. ERASE_RAF Function Packet Items ................................................................... 9–2<br />
9–2. DELETE_FILE Function Packet Items ................................................................. 9–5<br />
10–1. MOVE_SAF Function Packet Items .................................................................. 10–3<br />
10–2. CLOSE_SAF Function Packet Items ............................................................... 10–13<br />
xii 7830 9796–013
Tables<br />
1–1. Summary of PCFP Functions ........................................................................... 1–21<br />
8–1. Absolute and Relative Sequence Numbers (sample)....................................... 8–15<br />
10–1. Actions Performed by MOVE_SAF Function ................................................... 10–9<br />
B–1. Summary of FURPUR Commands ..................................................................... B–2<br />
C–1. Standard Method Performance Comparison ..................................................... C–3<br />
C–2. Copy Method Performance Comparison ........................................................... C–5<br />
7830 9796–013 xiii
Tables<br />
xiv 7830 9796–013
Section 1<br />
Using PCFP<br />
This manual is written to provide a general understanding of how to use PCFP and to<br />
serve as a specific reference for information on each of the PCFP functions.<br />
Documentation Updates<br />
This document contains all the information that was available at the time of publication.<br />
Changes identified after release of this document are included in problem list entry (PLE)<br />
18564441. To obtain a copy of the PLE, contact your <strong>Unisys</strong> service representative or<br />
access the current PLE from the <strong>Unisys</strong> Product <strong>Support</strong> Web site:<br />
http://www.support.unisys.com/all/ple/18564441<br />
Note: If you are not logged into the Product <strong>Support</strong> site, you will be asked to do so.<br />
The primary audience for this document is the programmer who has experience on the<br />
OS 2200 system and knows at least one of the programming languages from which you<br />
can call PCFP.<br />
This section explains how to use Program-Callable FURPUR (PCFP) and provides<br />
examples. These examples are intended to help you understand how PCFP works in<br />
general. They do not cover every application of PCFP. The examples show you<br />
• How to prepare a function packet before calling a function<br />
• How to handle return information<br />
After reading this section, you should have a general understanding of how to use PCFP<br />
within programs. Sections 2 – 10 contain detailed information on each PCFP function.<br />
Sections 11 – 13 contain detailed information on each language from which PCFP can be<br />
used.<br />
1.1. Definition of PCFP<br />
Designed to run on the OS 1100 and 2200 Extended Mode systems, Program-Callable<br />
FURPUR (PCFP) extends the capabilities of the FURPUR processor, making its<br />
capabilities available for applications written in C, FORTRAN, and COBOL. Providing a<br />
set of FURPUR-like functions, PCFP is a utility that provides you with a straightforward<br />
way to have programs perform the file and element handling capabilities of FURPUR<br />
without interrupting the flow of the program. PCFP allows you to make file handling<br />
decisions, include those decisions in your program by specifying packet parameters for a<br />
particular PCFP function, and call the function to operate on files you specify. Results<br />
7830 9796–013 1–1
Using PCFP<br />
are returned to your program either through the function packet or in a data structure you<br />
provide.<br />
You can call PCFP any number of times from within a program. Each call performs a<br />
PCFP operation on a single file or element, unless a function allows for a list of multiple<br />
files or elements. With some considerations and restrictions, you can also call PCFP<br />
simultaneously from multiple activities running in the same program. See 2.8 for<br />
additional information on multi-activity programs.<br />
Perform the following five steps to use PCFP:<br />
1. Include the appropriate data definition elements in your C, COBOL, or FORTRAN<br />
program. These data definition elements are part of the PCFP product release.<br />
2. Initialize the parameter packets.<br />
3. Set values to indicate the precise operation you want to perform.<br />
4. Call PCFP to perform the operation.<br />
5. Check the returned status for successful completion.<br />
No explicit linking is required to use PCFP in the extended-mode programming<br />
environment.<br />
1.2. File Types Operated on by PCFP<br />
Like FURPUR commands, PCFP functions operate on two types of files:<br />
• Random-access files (RAF), also referred to as mass storage files<br />
• Sequential-access files (SAF), also referred to as tape files<br />
A number of PCFP functions operate on a special type of RAF called a program file.<br />
There are two basic program file formats. The standard program file, referred to as a PF,<br />
has small variable-length tables. The large program, referred to as an LPF, has large<br />
fixed-length tables. For example, the PF has a normal maximum of 2,671 element table<br />
entries and can be expanded to 5,000 entries, while the LPF has a fixed maximum of<br />
26,146 element table entries.<br />
PF and LPF elements are limited to a maximum of 262,143 sectors of text for each<br />
element. A new program file type, the large element program, referred to as an LEPF,<br />
removes this limitation and allows elements to have over 262,143 sectors of text, if<br />
desired. An LEPF can be initialized with the small variable-length format of a standard<br />
program file (standard LEPF) or with the large fixed-length format of a large program file<br />
(large LEPF).<br />
All PCFP functions can operate on a PF, LPF, standard LEPF, or large LEPF.<br />
1–2 7830 9796–013
1.3. Calling PCFP Functions<br />
Using PCFP<br />
Figures 1–1, 1–6, and 1–11 show calls to three different PCFP functions. These figures<br />
illustrate PCFP functions of various complexities and with different mixes of input and<br />
output parameters.<br />
These figures contain logic charts depicting programs that set up parameters, call a<br />
PCFP function, and process the information returned by that PCFP function. The figures<br />
also contain supporting information, such as illustrations of the input parameters prior to<br />
calling the PCFP function and an illustration of a repeating return entry from a PCFP<br />
function that returns repeating information.<br />
In later sections of this manual, the information in these figures is shown in specific<br />
program language examples. Section 11 shows examples of these programs written in<br />
the C language. Section 12 shows examples of these programs written in COBOL.<br />
Section 13 shows examples of these programs written in FORTRAN.<br />
1.3.1. Calling PCFP to Delete a File<br />
Figure 1–1 shows the process associated with calling a PCFP function that requires<br />
minimal setup. In this figure, PCFP is called to delete the file A*B. Procedures 1 – 7 are<br />
explained following the figure.<br />
7830 9796–013 1–3
Using PCFP<br />
Figure 1–1. Calling the DELETE_FILE Function<br />
1–4 7830 9796–013
Procedure 1<br />
Using PCFP<br />
Clear the function packet to zeros to ensure that each item in the function packet is<br />
initially set at its default value. This allows you to concentrate on the values you want to<br />
change.<br />
Procedure 2<br />
Set the necessary items in the DELETE_FILE function packet:<br />
• Set INTERFACE_LEVEL to fp_interface_level_1 (which is defined as 1).<br />
• Set WORK_AREA_SIZE to fp_max_work_area_delete_file (1,000, which is the<br />
maximum work area size for the DELETE_FILE function).<br />
You do not need to set the other items in the function packet, either because the default<br />
value (0) is the desired value for these, or because PCFP uses these items to return<br />
information to the calling program. For example, in Figures 1–2 and 1–3, the items<br />
EXCLUSIVE_ASSIGN (a) and ZERO_RELEASED_STORAGE (b) in the specific part of the<br />
function packet are left initialized to FALSE (0).<br />
Figures 1–2 and 1–3 compare the items of the DELETE_FILE function packet to the<br />
function packet completed with the numeric equivalents for the items.<br />
0 INTERFACE_LEVEL<br />
1 a b<br />
2 WORK_AREA_SIZE<br />
3 SOFTWARE_LEVEL<br />
4<br />
5 GEN_DATE_TIME<br />
6<br />
7 ERROR_CLASS ERROR_FILE SUB_ERROR_CODE<br />
8 ERROR_CODE<br />
9 AUX_ERROR_CODE<br />
10 a b<br />
Figure 1–2. DELETE_FILE Function Packet Items<br />
7830 9796–013 1–5
Using PCFP<br />
0 1 0<br />
1 F F 0<br />
2 1000<br />
3 0<br />
4<br />
5 0<br />
6<br />
7 0 0 0<br />
8 0<br />
9 0<br />
10 F F 0<br />
Figure 1–3. DELETE_FILE Function Packet with Numeric Equivalents<br />
Procedure 3<br />
Clear the file identifier packet to zeros to ensure that each item in the packet is initially<br />
set at its default value. This allows you to concentrate on the values you want to<br />
change.<br />
Procedure 4<br />
Set the necessary items in the file identifier packet:<br />
• Set INTERFACE_LEVEL to fp_interface_level_1.<br />
• Set the QUALIFIER to A.<br />
• Set the FILENAME to B.<br />
You do not need to set the other items in the function packet, because the default value<br />
(0) is the desired value for these.<br />
Because DIRECTORY_ID is not set, PCFP uses the default directory-id for your run.<br />
Since F_CYCLE_TYPE and F_CYCLE are not set, PCFP uses the latest cycle for the file<br />
(relative cycle-0). Since READ_KEY and WRITE_KEY are not set, PCFP assumes the file<br />
has no read key and no write key.<br />
Figures 1–4 and 1–5 compare the items of the file identifier packet to the packet<br />
completed with the numeric and character equivalents for the items.<br />
1–6 7830 9796–013
0<br />
1 INTERFACE_LEVEL<br />
2 DIRECTORY_ID<br />
3 DIRECTORY_ID<br />
4<br />
5 QUALIFIER<br />
6<br />
7<br />
8 FILENAME<br />
9<br />
10 F_CYCLE_TYPE F_CYCLE<br />
11 READ_KEY<br />
12 READ_KEY<br />
13 WRITE_KEY<br />
14 WRITE_KEY<br />
Figure 1–4. File Identifier Packet Items<br />
Using PCFP<br />
7830 9796–013 1–7
Using PCFP<br />
0 0<br />
1 0 1<br />
2 0<br />
3 0 0<br />
4<br />
5 A<br />
6<br />
7<br />
8 B<br />
9<br />
10 0 0<br />
11 0<br />
12 0 0<br />
13 0<br />
14 0 0<br />
Figure 1–5. File Identifier Packet Items with Numeric Equivalents<br />
Procedure 5<br />
In languages other than COBOL, PCFP functions are called as functions. In COBOL,<br />
PCFP functions are called as subroutines, using the COBOL CALL statement. The<br />
DELETE_FILE function is called with two parameters:<br />
• The function packet<br />
• The file identifier packet<br />
After calling the PCFP function, your program should check the item ERROR_CLASS in<br />
the function packet to determine if the function produced an error.<br />
Procedure 6<br />
One suggested way of performing error processing is simply to display a message<br />
denoting the error. Note that the error code returned in the function packet is in ELMS<br />
format. This means that in order to get a true explanatory error message for the error<br />
code, your program (if written in C language) can call the Extended Message Language<br />
System (ELMS) with this error code as input. In Sections 11 – 13, the programs that<br />
implement this example simply display the error code along with an explanatory prefix.<br />
Procedure 7<br />
Before your program exits, you may want it to display a completion message to confirm<br />
that the operation PCFP was called to perform completed successfully. The programs in<br />
Sections 11 – 13 that implement this example display a simple completion message<br />
when no error is detected.<br />
1–8 7830 9796–013
1.3.2. Calling PCFP to Copy a File<br />
Using PCFP<br />
Figure 1–6 shows the process used to call a PCFP function that requires more setup<br />
than the DELETE_FILE function required. In this figure, PCFP is called to copy the<br />
contents of mass storage file A*B(2) to the mass storage file with an internal name of<br />
FILE2. Procedures 1 – 9 are explained following the figure.<br />
Figure 1–6. Calling the COPY_RAF_RAF Function<br />
7830 9796–013 1–9
Using PCFP<br />
Procedure 1<br />
Clear the function packet to zeros to ensure that each item in the function packet is set<br />
at its default value. This allows you to concentrate on the values you want to change.<br />
Procedure 2<br />
Set the necessary items in the COPY_RAF_RAF function packet:<br />
• Set INTERFACE_LEVEL to fp_interface_level_1 (1).<br />
• Set WORK_AREA_SIZE to fp_max_work_area_copy_raf_raf (60,000 is the maximum<br />
work area size for the COPY_RAF_RAF function).<br />
You do not need to set the other items in the function packet, either because the default<br />
value (0) is the desired value for these, or because PCFP uses these items to return<br />
information to the calling program. For example, in Figures 1–7 and 1–8, the items<br />
PREVENT_OVERCOPY (a) and ZERO_RELEASED_STORAGE (b) in the specific part of<br />
the function packet are left initialized to FALSE, and the item STORAGE_TO_RELEASE is<br />
left initialized to none.<br />
Figures 1–7 and 1–8 compare the items of the COPY_RAF_RAF function packet to the<br />
function packet completed with the numeric equivalents for the items.<br />
0 INTERFACE_LEVEL<br />
1 a b<br />
2 WORK_AREA_SIZE<br />
3 SOFTWARE_LEVEL<br />
4<br />
5 GEN_DATE_TIME<br />
6<br />
7 ERROR_CLASS ERROR_FILE SUB_ERROR_CODE<br />
8 ERROR_CODE<br />
9 AUX_ERROR_CODE<br />
10 a c STORAGE_TO_RELEASE<br />
11 AMOUNT_COPIED<br />
Figure 1–7. COPY_RAF_RAF Function Packet Items<br />
1–10 7830 9796–013
0 1 0<br />
1 F F 0<br />
2 60000<br />
3 0<br />
4<br />
5 0<br />
6<br />
7 0<br />
8 0<br />
9 0<br />
10 F 0 F 0<br />
11 0<br />
Using PCFP<br />
Figure 1–8. COPY_RAF_RAF Function Packet with Numeric Equivalents<br />
Procedure 3<br />
Clear the source file identifier packet to zero to ensure that each item in the packet is set<br />
at its default value. This allows you to concentrate on the values you want to change.<br />
Procedure 4<br />
Set the necessary items in the source file identifier:<br />
• Set INTERFACE_LEVEL to fp_interface_level_1 (1).<br />
• Set QUALIFIER to A.<br />
• Set FILENAME to B.<br />
• Set F_CYCLE_TYPE to abs (1).<br />
• Set F_CYCLE to 2.<br />
You do not need to set the other items in the source file identifier packet, because the<br />
default value (0) is the desired value for these.<br />
Figures 1–9 and 1–10 compare the items of the source file identifier packet to the packet<br />
completed with the numeric and character equivalents for the items.<br />
7830 9796–013 1–11
Using PCFP<br />
0<br />
1 INTERFACE_LEVEL<br />
2 DIRECTORY_ID<br />
3 DIRECTORY_ID<br />
4<br />
5 QUALIFIER<br />
6<br />
7<br />
8 FILENAME<br />
9<br />
10 F_CYCLE_TYPE F_CYCLE<br />
11 READ_KEY<br />
12 READ_KEY<br />
13 WRITE_KEY<br />
14 WRITE_KEY<br />
Figure 1–9. Source File Identifier Packet Items<br />
0 0<br />
1 0 1<br />
2 0<br />
3 0 0<br />
4<br />
5 A<br />
6<br />
7<br />
8 B<br />
9<br />
10 1 2<br />
11 0<br />
12 0 0<br />
13 0<br />
14 0 0<br />
Figure 1–10. Source File Identifier Packet Items with Numeric Equivalents<br />
1–12 7830 9796–013
Procedure 5<br />
Using PCFP<br />
Clear the destination file identifier packet to zero to ensure that each item in the packet<br />
is set at its default value. This allows you to concentrate on the values you want to<br />
change.<br />
Procedure 6<br />
Set the necessary items in the destination file identifier packet:<br />
• Set INTERFACE_LEVEL to fp_interface_level_1 (1).<br />
• Set FILENAME to FILE2.<br />
You do not need to set the other items in the destination file identifier packet because<br />
the default value (0) is the desired value for these.<br />
The illustration of the destination file identifier packet is not shown here because it is<br />
similar to file identifier packets illustrated earlier.<br />
Procedure 7<br />
In languages other than COBOL, PCFP functions are called as functions. In COBOL,<br />
PCFP functions must be called as procedures, using the COBOL CALL statement. This<br />
function is called with three parameters:<br />
• The function packet<br />
• The source file identifier packet<br />
• The destination file identifier packet<br />
After calling the PCFP function, your program should check the item ERROR_CLASS in<br />
the function packet to determine if the function produced an error.<br />
Procedure 8<br />
As suggested in the first example, a C language program can present the error code to<br />
ELMS to get an explanatory message that describes the error condition. In Sections<br />
11 – 13, the programs that implement this example display the error code along with an<br />
explanatory prefix.<br />
Procedure 9<br />
Before your program exits, you may want it to display a message that confirms the<br />
successful completion of the copy operation that PCFP was called to perform. In<br />
Sections 11 – 13, the programs that implement this example display a message denoting<br />
the number of tracks of data that were successfully copied.<br />
7830 9796–013 1–13
Using PCFP<br />
1.3.3. Calling PCFP to Acquire Element Information from a<br />
Program File<br />
Figure 1–11 shows the process used to call a PCFP function that requires a setup of the<br />
following:<br />
• Function and file identifier packet<br />
• The definition of an area to contain repeating return information<br />
In this example, PCFP is called to acquire all information about the symbolic elements in<br />
the program file A*B. A return area capable of accepting up to 100 return entries is<br />
made available to PCFP. Procedures 1 – 7 are explained following the figure.<br />
Figure 1–11. Calling the ACQ_ELT_INFO Function<br />
1–14 7830 9796–013
Procedure 1<br />
Using PCFP<br />
Clear the function packet to zeros to ensure that each item in the function packet is set<br />
at its default value. This allows you to concentrate on the values you want to change.<br />
Procedure 2<br />
Set the necessary items in the ACQ_ELT_INFO function packet:<br />
• Set INTERFACE_LEVEL to fp_interface_level_1 (1).<br />
• Set WORK_AREA_SIZE to fp_max_work_area_acq_elt_info (20,000 is the maximum<br />
work area size for the ACQ_ELT_INFO function).<br />
• Set RTN_AREA_SIZE large enough for 100 element entries. (100 entries times the<br />
word length of the long form of the element return entry, which is 16).<br />
• Set SYM_TYPE (d) to TRUE. This indicates that PCFP is to select only symbolic<br />
elements.<br />
• Set INFO_DETAIL to long. This indicates that PCFP is to return the long form of<br />
element return entries.<br />
You do not need to set the other items in the function packet, either because the default<br />
value (0) is the desired value for these, or because PCFP uses these items to return<br />
information to the calling program. In particular, the remaining items denoting element<br />
type selection [ABS_TYPE (a), OMN_TYPE (b), and REL_TYPE (c)] and the items denoting<br />
element subtype selection (arrays e and f) are left initialized to FALSE. This means that<br />
only symbolic element types are selected; and within this type, there is no subtype<br />
restriction. Thus PCFP selects all symbolic elements having any subtype.<br />
Figures 1–12 and 1–13 compare the items of the ACQ_ELT_INFO function packet to the<br />
function packet completed with the numeric equivalents for the items.<br />
7830 9796–013 1–15
Using PCFP<br />
0 INTERFACE_LEVEL<br />
1 a b<br />
2 WORK_AREA_SIZE<br />
3<br />
4<br />
5<br />
6<br />
SOFTWARE_LEVEL<br />
GEN_DATE_TIME<br />
7 ERROR_CLASS ERROR_FILE SUB_ERROR_CODE<br />
8 ERROR_CODE<br />
9 AUX_ERROR_CODE<br />
10<br />
11 RTN_AREA_SIZE<br />
12<br />
13 NUM_RTN_ENTRIES<br />
14<br />
15 RTN_ENTRY_SIZE NUM_ENTRIES_IN_RTN_AREA<br />
16<br />
17<br />
18<br />
19<br />
20<br />
21<br />
22<br />
23<br />
24<br />
25 a b c d<br />
ELT_NAME<br />
ELT_VERSION<br />
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<br />
27 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<br />
28 f f f f f f f f f f f f f f f f f f CHAR_TYPE<br />
29<br />
30<br />
31<br />
32<br />
MIN_DATE_TIME<br />
MAX_DATE_TIME<br />
Figure 1–12. ACQ_ELT_INFO Function Packet Items (cont.)<br />
33 MIN_SEQ_NUM<br />
1–16 7830 9796–013
34 MAX_SEQ_NUM<br />
35 MIN_SIZE<br />
36 MAX_SIZE<br />
37 DELETION INFO_DETAIL<br />
38 NUM_SELECTED<br />
39<br />
40<br />
41<br />
42<br />
Figure 1–12. ACQ_ELT_INFO Function Packet Items<br />
Using PCFP<br />
7830 9796–013 1–17
Using PCFP<br />
0 1 0<br />
1 F F 0<br />
2 2000<br />
3<br />
4<br />
5<br />
6<br />
7 0 0 0<br />
8 0<br />
9 0<br />
10 0<br />
11 1600<br />
12 0<br />
13 0<br />
14 0<br />
15 0 0<br />
16 0<br />
17 0<br />
18 0<br />
19<br />
20<br />
21<br />
22<br />
23<br />
24<br />
25 F F F T<br />
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<br />
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<br />
28 F F F F F F F F F F F F F F F F F F 0<br />
29<br />
30<br />
Figure 1–13. ACQ_ELT_INFO Function Packet Items with Numeric Equivalents<br />
(cont.)<br />
1–18 7830 9796–013<br />
0<br />
0<br />
0<br />
0<br />
0
31<br />
32<br />
33 0<br />
34 0<br />
35 0<br />
36 0<br />
37 0 1<br />
38 0<br />
39 0<br />
40 0<br />
41 0<br />
42 0<br />
Using PCFP<br />
Figure 1–13. ACQ_ELT_INFO Function Packet Items with Numeric Equivalents<br />
Procedure 3<br />
7830 9796–013 1–19<br />
0<br />
Clear the file identifier packet to zeros to ensure that each item in the packet is set at its<br />
default value. This allows you to concentrate on the values you want to change.<br />
Procedure 4<br />
Set the necessary items in the file identifier packet:<br />
• Set INTERFACE_LEVEL to fp_interface_level_1 (1).<br />
• Set QUALIFIER to A.<br />
• Set FILENAME to B.<br />
You do not need to set the other items in the file identifier packet, because the default<br />
value of zero is the desired value for these.<br />
See Figures 1–4 and 1–5 for an illustration of the file identifier packet.<br />
Procedure 5<br />
This function is called with three parameters:<br />
• The function packet<br />
• The file identifier packet<br />
• The return area<br />
After calling the function, your program should check the function packet to determine if<br />
any errors occurred.
Using PCFP<br />
Procedure 6<br />
As suggested in the other two examples, a C language program can present the error<br />
code to ELMS to get an explanatory message that describes the error condition. In<br />
Sections 11 – 13, the programs that implement this example display the error code along<br />
with an explanatory prefix.<br />
Procedure 7<br />
Before your program exits, you will want it to perform some processing of the<br />
information returned by PCFP in the return area. In Sections 11 – 13, the programs that<br />
implement this example display a header line denoting the number of elements selected<br />
using the item NUM_RTN_ENTRIES that PCFP returned in the function packet.<br />
Following this, the programs display a line for each element in the return area, showing<br />
its name, version, sequence number, and subtype name.<br />
1–20 7830 9796–013
1.4. Summary of PCFP Functions<br />
Using PCFP<br />
Table 1–1 presents a summary, in alphabetical order, of all the functions PCFP provides.<br />
The first column gives the function name. The second column gives a concise<br />
description of the function. The third column gives analogous FURPUR commands for<br />
users who are familiar with the FURPUR command language. Note that in most cases,<br />
the PCFP functions provide capabilities beyond those available in FURPUR. Also, in<br />
some cases capabilities of a FURPUR command are split across multiple PCFP functions.<br />
The fourth column gives the subsection of this manual that describes the PCFP function.<br />
You can refer to Appendix B. This appendix provides a complete list of FURPUR<br />
commands and options and the analogous PCFP function, when applicable.<br />
Function Name<br />
Table 1–1. Summary of PCFP Functions<br />
Description<br />
ACQ_BASIC_PF_INFO Returns global information about a specified program<br />
file.<br />
ACQ_ELT_INFO Returns information about a set of elements in a<br />
program file that satisfy specified criteria.<br />
ACQ_FILE_INFO Returns directory information about a single specified<br />
file.<br />
ACQ_FILE_LIST Returns directory information about a set of files that<br />
satisfy specified criteria.<br />
ACQ_OM_EP_INFO Returns information about a set of object- module<br />
entry points in a program file that satisfy specified<br />
criteria.<br />
ACQ_PROC_INFO Returns information about a set of procedures in a<br />
program file that satisfy specified criteria.<br />
ACQ_REL_EP_INFO Returns information about a set of relocatable entry<br />
points in a program file that satisfy specified criteria.<br />
CHG_ELT Changes attributes of a set of elements in a program<br />
file that satisfy specified criteria.<br />
CHG_FILE Changes directory attributes of a single specified<br />
cataloged file and initializes an empty file as a<br />
program file.<br />
CHG_FILE_CYC Changes the F-cycle limit for the files in a specified<br />
F-cycle series.<br />
CHG_FILE_KEYS Changes the read or write key for the files in a<br />
specified F-cycle series.<br />
CHG_FILE_NAME Changes the qualifier or file name for the files in a<br />
specified F-cycle series.<br />
Analogous<br />
FURPUR<br />
Command<br />
Sub-<br />
section<br />
@PRT,TL 6.1<br />
@PRT,TL 6.2<br />
@PRT,F 3.1<br />
@PRT,F<br />
@PRT,I<br />
7830 9796–013 1–21<br />
3.2<br />
@PRT,TL 6.4<br />
@PRT,TL 6.5<br />
@PRT,TL 6.3<br />
@CHG,AORS;<br />
@CYCLE<br />
@CHG,ET;<br />
@CHG,V;<br />
@CHG,W;<br />
@CHG,Z;<br />
@ENABLE<br />
8.1<br />
4.1<br />
@CYCLE 4.2<br />
@CHG 4.4<br />
@CHG,N 4.5
Using PCFP<br />
Function Name<br />
Table 1–1. Summary of PCFP Functions<br />
Description<br />
CHG_FILE_SEC Changes security attributes for the files in a specified<br />
F-cycle series.<br />
Analogous<br />
FURPUR<br />
Command<br />
@CHG,K;<br />
@CHG,P;<br />
@CHG,Q<br />
Sub-<br />
section<br />
CLOSE_SAF Writes a logical-end mark to a tape file. @MARK 10.2<br />
COPY_ELT Copies a set of elements that satisfy specified criteria<br />
from one program file to another.<br />
COPY_OMN_ELT_RAF Copies a single omnibus element from a program file<br />
to a mass storage file.<br />
COPY_RAF_OMN_ELT Creates a single omnibus element in a program file<br />
from the contents of a mass storage file.<br />
COPY_RAF_RAF Copies the contents of one mass storage file into<br />
another mass storage file.<br />
COPY_RAF_SAF Copies the contents of one mass storage file into a<br />
tape file.<br />
COPY_RAF_SYM_ELT Creates a single symbolic element in a program file<br />
from the contents of a mass storage file containing<br />
SDF text.<br />
COPY_SAF_RAF Copies a single logical file from a tape file to a mass<br />
storage file.<br />
COPY_SAF_SAF Copies a single logical file from one tape file to<br />
another tape file.<br />
COPY_SYM_ELT_RAF Copies a single symbolic element from a program file<br />
to a mass storage file.<br />
DELETE_ELT Deletes a set of elements in a program file that<br />
satisfy specified criteria.<br />
@COPY,P;<br />
@COPY,AORS<br />
1–22 7830 9796–013<br />
4.3<br />
7.1<br />
@COPY,IO 7.4<br />
@COPY,IO 7.5<br />
@COPY 5.1<br />
@COPY,G 5.2<br />
@COPY,I 7.3<br />
@COPY,G 5.3<br />
@COPY 5.4<br />
@COPY,I 7.2<br />
@DELETE,AORS;<br />
@PACK,AORS<br />
DELETE_FILE Deletes a single file. @DELETE 9.2<br />
ERASE_RAF Releases or zero-fills mass storage in a file. @ERS 9.1<br />
MOVE_SAF Repositions a tape file. @MOVE;<br />
@REWIND<br />
PACK_PF Releases dead space due to deleted elements from a<br />
program file.<br />
8.2<br />
10.1<br />
@PACK 8.4<br />
PREP_PF Creates entry point tables in a program file. @PREP 8.5<br />
UNDELETE_ELT Undeletes a set of elements in a program file that<br />
satisfy specified criteria.<br />
@DELETE,UAORS 8.3
1.5. PCFP Processor<br />
Using PCFP<br />
The PCFP level and PCFP generation date and time are returned by PCFP to the calling<br />
program in each function packet (see 2.4.1). However, this information is not visible to<br />
the user unless the calling program formats and displays it.<br />
The PCFP processor provides a convenient method of displaying the PCFP level and the<br />
PCFP generation date and time from within an OS 2200 runstream. Call the PCFP<br />
processor with the following command:<br />
@PCFP<br />
The PCFP processor displays a processor identification line in the following format:<br />
PCFP level (yymmdd hhmm:ss) yyyy mmm dd dow hhmm:ss<br />
where:<br />
level<br />
is the PCFP level.<br />
yymmdd hhmm:ss<br />
is the PCFP generation date and time.<br />
yyyy mmm dd dow hhmm:ss<br />
is the current date and time.<br />
The PCFP processor displays the PCFP copyright notice and the following termination<br />
line:<br />
END PCFP.<br />
7830 9796–013 1–23
Using PCFP<br />
1–24 7830 9796–013
Section 2<br />
Functions of PCFP<br />
This section describes the following information about PCFP functions:<br />
• The general form of all functions that are part of PCFP<br />
• The data types used in this manual to describe the parameters passed to and from<br />
PCFP functions<br />
• The detailed definitions of certain parameters and parts of parameters that are used<br />
by most PCFP functions<br />
The information presented in this section is not language dependent. Certain special<br />
considerations exist for each language from which you can call PCFP. Consult the<br />
appropriate section (11, 12, or 13) for these special considerations.<br />
2.1. Typical Form of PCFP Functions<br />
In C and FORTRAN, each PCFP function is a subroutine that is called as a function with<br />
parameters. In COBOL, each PCFP function is called as a subroutine with parameters.<br />
All PCFP parameters are data structures that contain a number of data items. Before<br />
calling PCFP, the calling program sets the data items in the parameters for the precise<br />
task to be performed by the function. When the calling program calls a PCFP function,<br />
PCFP passes back the results of the task in the parameters and the function-return<br />
value. The calling program examines these return values after it calls PCFP. The<br />
parameters are discussed later in this subsection.<br />
Each parameter structure used by PCFP is defined in this manual. Each structure is<br />
defined in a diagram giving the layout of the structure and names of the items contained<br />
in the structure. A list of the items follows each diagram, giving the name of the item,<br />
its data type, the list of values that the item can assume (where applicable), and a short<br />
description of the item. For the most part, the names of items and values are the same<br />
across all languages from which PCFP can be called. However, language-specific<br />
differences are necessary in some cases, and are described in Sections 11 – 13.<br />
7830 9796–013 2–1
Functions of PCFP<br />
The following are parameters that most PCFP functions use:<br />
• Function Packet<br />
This structure is the first parameter of each PCFP function. It acts both as an input<br />
parameter and an output parameter. It is the structure through which the calling<br />
program specifies all options that apply to the function. PCFP also uses this<br />
parameter to pass certain fixed-sized return items back to the calling program. The<br />
function packet for each function consists of generic parts, which are the same for<br />
many or all functions, and a specific part, which contains items specific to the<br />
individual function. The generic parts of the function packet are described in 2.4.1<br />
and 2.4.2. The specific parts are described in Sections 3 – 10.<br />
• File Identifier<br />
This input parameter is a structure that uniquely identifies a file to be operated on by<br />
a function. Functions that do not operate on an individual file have no parameter of<br />
this type. Functions that operate on a single file have a single file-identifier<br />
parameter. Copy functions, which operate on two files at once, have two<br />
file-identifier parameters: one for the source file from which data is copied, and one<br />
for the destination file, to which data is copied. The file identifier parameter is<br />
described in 2.3.<br />
• Return Area<br />
Some functions return to the calling program information about a list of files or<br />
elements. These functions return a variable-length array of return entries, one entry<br />
for each file or element in the list. For these functions, the calling program must<br />
supply an output parameter, called the return area, into which PCFP places as many<br />
of the return entries as will fit into this area. The calling program specifies the size of<br />
this return area parameter in the function packet.<br />
• Work Area<br />
Each PCFP function requires a scratch data area, called the work area, in which to do<br />
its calculations. For this release of PCFP, the calling program does not supply this<br />
parameter; PCFP allocates and releases it dynamically. (In COBOL and FORTRAN<br />
programs, this parameter is omitted; in C programs, you must specify the value<br />
NULL for this parameter.) However, the calling program must specify the size of the<br />
work area that PCFP allocates. The function descriptions in Sections 3 – 10 indicate<br />
the work area size requirements for each function.<br />
The function value returned by each PCFP function (in C and FORTRAN) is an ELMS<br />
condition-id. This condition-id indicates if the function completed successfully or, if it did<br />
not complete successfully, why not.<br />
2–2 7830 9796–013
Functions of PCFP<br />
All of the above parameters are moved to a dynamic basic mode bank where they are<br />
operated on by PCFP. In addition to these parameters, PLUS stack space and PLUS<br />
work space are also allocated in the dynamic bank. The maximum possible size of the<br />
dynamic basic mode bank limits the maximum size that can be specified for the return<br />
area and the work area. The maximum size for most PCFP functions is the difference<br />
between the minimum relative address, defined by MIN_DATA_ADDR, and the<br />
maximum relative address, defined by MAX_DATA_ADDR. These definitions are<br />
contained in the copy/include element FP$DEFS. Some functions require a different<br />
minimum relative address or a different maximum relative address. In these cases the<br />
function descriptions in Sections 3 – 10 indicate the minimum and maximum addresses<br />
that apply for the function.<br />
2.2. Data Types<br />
The following data types are used in the item descriptions throughout this manual.<br />
These data types are described here in a language-independent manner. Any<br />
language-specific considerations are described in Sections 11 – 13.<br />
Character<br />
The item contains an ASCII character string, the maximum length of which is given in the<br />
item description. The calling program must specify character values shorter than the<br />
maximum by one of the following means:<br />
• Left-justified within the item, and space-filled on the right. This is the typical method<br />
for specifying strings in languages other than C.<br />
• Left-justified within the item, and null-terminated on the right. (Null-terminated<br />
means that the string is followed immediately by a null character [integer code 0],<br />
and that all characters following the null are insignificant.) This is the typical method<br />
for specifying strings in C.<br />
Either of these methods can be used by a calling program written in any language. It is<br />
permissible for some strings to be specified using one method, and others to be<br />
specified using the other method.<br />
In character items input to PCFP, both uppercase and lowercase letters are allowed.<br />
PCFP treats each lowercase letter as its uppercase equivalent except where noted<br />
otherwise. In character items returned by PCFP, letters are uppercase only, except<br />
where noted otherwise.<br />
Integer<br />
The item may assume integer values. In some cases, “unsigned” is also specified to<br />
indicate that only nonnegative integer values are legal. Unless the range of integer<br />
values that can be assumed by the item is particularly important, it is not noted in the<br />
item description (but can be inferred from the structure layout). Integer items are<br />
allocated with sizes large enough so that the size of the item poses no significant<br />
restriction on the capabilities of PCFP.<br />
Condition<br />
The item can assume only the values TRUE and FALSE. Internally, TRUE is represented<br />
by 1, and FALSE is represented by 0.<br />
7830 9796–013 2–3
Functions of PCFP<br />
Condition Array<br />
A condition array is a contiguous grouping of related 1-bit condition items. Individual<br />
condition items are numbered from left to right in increasing order, usually starting with<br />
0. Specify the condition item number as a subscript of the condition array name to<br />
identify an individual condition item in the array. For example, if ABS_SUBTYPE is a<br />
condition array of 18 condition items, the first (left-most) condition item would be<br />
identified as ABS_SUBTYPE(0) and the last (right-most) condition item would be<br />
identified as ABS_SUBTYPE(17).<br />
Value-List<br />
The values the item can assume are listed explicitly. (Each value is a named constant<br />
followed by its internal integer code.) The structure definitions supplied with PCFP<br />
include definitions for the enumerated constants.<br />
The value represented by zero internally is chosen to be the one that is likely to be used<br />
most frequently. This allows a programmer to zero fill an entire packet containing many<br />
items and to fill in only those items that are applicable to the task. In those cases where<br />
the value-list does not have a legal value for zero, the calling program must always set<br />
the item explicitly.<br />
Date-Time<br />
The item can assume values representing date and time. Each item with this data type<br />
is two words long, and contains the following items:<br />
• Year: unsigned integer in H1 of first word. Contains the year part of the date.<br />
• Month: unsigned integer range (1 – 12) in Q3 of first word. Contains the numeric<br />
value of the month part of the date.<br />
• Day: unsigned integer range (1 – 31) in Q4 of first word. Contains the numeric value<br />
of the day-of-the-month part of the date. For the COBOL language only, this item is<br />
named DAY-OF-MONTH to avoid conflict with the COBOL reserved word DAY.<br />
• Milliseconds: unsigned integer range (0 – 86,399,999) in second word. Contains the<br />
time past midnight in milliseconds. All time values returned by PCFP are rounded to<br />
the nearest second, so when an item of this type is returned by PCFP, it is always<br />
divisible by 1,000.<br />
In addition to these individual items, a method is provided in each language to compare<br />
date-time values as entire entities. These methods are described in Sections 11 – 13.<br />
2.3. File Identifiers<br />
PCFP functions that operate on a specific file (or two specific files) must have a file<br />
identifier that uniquely names each file that the function is to operate upon. For the sake<br />
of consistency, the file identifier used by all PCFP functions has the same format. This<br />
subsection explains all the items contained in this file identifier. See Figure 2–1.<br />
The file identifier contains the following four items that uniquely identify a file:<br />
• Directory-id<br />
2–4 7830 9796–013
• Qualifier<br />
• File name<br />
• F-cycle<br />
Functions of PCFP<br />
In addition to these items, the file identifier contains an interface level number, an Fcycle<br />
type, which denotes the type of F-cycle (absolute, relative, unspecified) that is<br />
specified, and read/write keys.<br />
In the file identifier, all defined items contain values that the calling program inputs to<br />
PCFP. Those parts of the file identifier for which no item is defined must contain zero<br />
when PCFP is called. PCFP never alters any part of a file identifier parameter. Thus, the<br />
same file identifier can be input to multiple functions that are to operate on the same file.<br />
Before calling a PCFP function, the calling program must initialize its file identifier<br />
parameters (if any). The calling program should do this first by zero-filling the entire<br />
structure. Sections 11 – 13 describe a method for doing this for each language from<br />
which PCFP can be called.<br />
The file identifier structure is defined in copy/include element FP$FILE$ID. This element<br />
must be included in any program that calls a PCFP function.<br />
0<br />
1 INTERFACE_LEVEL<br />
2 DIRECTORY_ID<br />
3 DIRECTORY_ID<br />
4<br />
5 QUALIFIER<br />
6<br />
7<br />
8 FILENAME<br />
9<br />
10 F_CYCLE_TYPE F_CYCLE<br />
11 READ_KEY<br />
12 READ_KEY<br />
13 WRITE_KEY<br />
14 WRITE_KEY<br />
Figure 2–1. File Identifier Packet Items<br />
7830 9796–013 2–5
Functions of PCFP<br />
Item Descriptions<br />
INTERFACE_LEVEL<br />
Indicates the interface level of structure definitions used to code this call to PCFP.<br />
The calling program must set this item to the value FP_INTERFACE_LEVEL_1.<br />
Data Type: unsigned integer<br />
DIRECTORY_ID<br />
Indicates the name of the directory in which the file is defined. Currently, the only<br />
legal values are the character strings STD and SHARED. A null value indicates the<br />
default directory for the run, while a value of spaces indicates the implied directory<br />
for the run.<br />
Note that the default directory for a run is set by using the Exec command @QUAL<br />
with the D option, while the implied directory for the run is set by using the @QUAL<br />
command with no option specified.<br />
Data Type: characters (6)<br />
QUALIFIER<br />
Indicates the qualifier for the file. A null value indicates the default qualifier for the<br />
run. A value of all spaces indicates the implied qualifier for the run.<br />
Note that the default qualifier for a run is set by using the Exec command @QUAL<br />
with the D option. The implied qualifier for a run is set by using @QUAL with no<br />
option specified.<br />
Data Type: characters (12)<br />
FILENAME<br />
Indicates the basic name of the file, which the calling program must always specify.<br />
If all items in the file identifier structure other than INTERFACE_LEVEL and<br />
FILENAME are zero or null, PCFP interprets the file name as an internal name of a<br />
file already assigned or known to the run.<br />
Data Type: characters (12)<br />
2–6 7830 9796–013
F_CYCLE_TYPE<br />
Functions of PCFP<br />
Indicates whether F_CYCLE contains an absolute F-cycle value, a relative F-cycle<br />
value, or no F-cycle value.<br />
Data Type: value-list<br />
UNSPECIFIED = 0<br />
An F_CYCLE_TYPE of UNSPECIFIED refers to the latest F-cycle of an F-cycle<br />
series, except for functions that apply to an entire F-cycle series (these are<br />
CHG_FILE_CYC, CHG_FILE_SEC, CHG_FILE_KEYS, and CHG_FILE_NAME). For<br />
the functions that apply to an entire F-cycle series, the calling program must set<br />
this item to UNSPECIFIED.<br />
ABS = 1<br />
REL = 2<br />
F_CYCLE<br />
Indicates the F-cycle of the file. If the calling program sets F_CYCLE_TYPE =<br />
UNSPECIFIED, it must set this item to 0. If the calling program sets F_CYCLE_TYPE<br />
= ABS, it must set this item to a value between 1 and 999 inclusive. If the calling<br />
program sets F_CYCLE_TYPE = REL, it must set this item to a value between -31<br />
and 1 inclusive.<br />
Data Type: signed integer range (-31 through 999)<br />
READ_KEY<br />
Indicates the read key that PCFP is to use to assign the file. If the calling program<br />
supplies a null value for this item, PCFP uses no read key when it attempts to assign<br />
the file. If the file is already assigned prior to calling PCFP, PCFP ignores this item.<br />
Data Type: characters (6)<br />
WRITE_KEY<br />
Indicates the write key that PCFP is to use to assign the file. If the calling program<br />
supplies a null value for this item, PCFP uses no write key when it attempts to<br />
assign the file. If the file is already assigned prior to calling PCFP, PCFP ignores this<br />
item.<br />
Data Type: characters (6)<br />
7830 9796–013 2–7
Functions of PCFP<br />
2.4. Function Packet<br />
The function packet acts as both an input and an output parameter. It is a structure<br />
through which the calling program specifies all options that apply to the function. This<br />
same structure is also used by PCFP to pass certain fixed-size return items back to the<br />
calling program.<br />
The function packet contains the following parts:<br />
• A generic part, which is the same for all functions, is specified at the start of each<br />
function packet. This part is described in 2.4.1.<br />
• A return-information part, which describes the return area used by the function. This<br />
part of the function packet exists only for those functions that have a return area<br />
parameter. This part is described in 2.4.2.<br />
• A specific part, which contains items specific to the individual function. The specific<br />
part of each function packet is described in Sections 3 – 10.<br />
In the function packet descriptions, those items that are explicitly labeled as “returned”<br />
contain values that PCFP returns to the calling program. These are the only items in the<br />
function packet that PCFP alters. All other items contain values that the calling program<br />
inputs to PCFP. PCFP examines only the input items from the function packet. The<br />
function packets also contain areas for which no item is defined; the calling program<br />
must initialize these areas to zero before calling PCFP.<br />
Before calling a PCFP function, the calling program must set up the function packet. The<br />
program does this first by zero-filling the entire structure. Sections 11 – 13 describe a<br />
method for doing this for each language from which PCFP can be called. Next, the<br />
calling program must explicitly set each input item in the packet for which a value of zero<br />
is not the desired value.<br />
2.4.1. Generic Part of the Function Packet<br />
The generic part of the function packet is the first part of the function packet for every<br />
PCFP function. To reduce repetition, the description of this part appears once here, and<br />
is not repeated in the descriptions of the individual functions. This part of the function<br />
packet must be initialized by the calling program before every call to a PCFP function.<br />
2–8 7830 9796–013
Functions of PCFP<br />
The structure of this part is defined in copy/include element FP$GENERIC. This element<br />
must be included in your program before any copy/include element that defines a<br />
specific function packet. See Figure 2–2.<br />
0 INTERFACE_LEVEL<br />
1 a b c<br />
2 WORK_AREA_SIZE<br />
3 SOFTWARE_LEVEL<br />
4<br />
5 GEN_DATE_TIME<br />
6<br />
7 ERROR_CLASS ERROR_FILE SUB_ERROR_CODE<br />
8 ERROR_CODE<br />
9 AUX_ERROR_CODE<br />
Item Descriptions<br />
INTERFACE_LEVEL<br />
Figure 2–2. Generic Part of the Function Packet<br />
Indicates the level of data structure definitions used for this function. All PCFP<br />
functions initially use a value of FP_INTERFACE_LEVEL_1. As new features are<br />
implemented for a function, it is sometimes necessary to expand the data structures<br />
(function packet, return entries and/or other special return information). When this<br />
occurs, the function packet interface level is increased by 1. The individual function<br />
packet documentation in Sections 3 – 10 describes the most current interface level<br />
for each function that supports interface levels other than FP_INTERFACE_LEVEL_1.<br />
The interface level is changed to ensure compatibility for existing function calls.<br />
Existing programs with older interface levels continue to operate correctly with no<br />
program changes. To use the new features, it is necessary to modify the program to<br />
use the new interface level and the associated new data structures.<br />
It is recommended that new programs and new function calls always use the most<br />
current interface level for each function. Data structures shown in this manual<br />
always correspond to the most current interface level. Data structures for older<br />
interface levels are shown in comments in the associated copy/include elements.<br />
Data Type: unsigned integer<br />
7830 9796–013 2–9
Functions of PCFP<br />
a = WAIT_ON_FACILITIES<br />
Indicates whether PCFP should wait on facilities (if this is necessary to perform the<br />
function requested). If the calling program sets this item to TRUE, PCFP waits<br />
indefinitely for the facilities required to perform the function. If the calling program<br />
sets this item to FALSE, PCFP returns with an error condition if all required facilities<br />
are not immediately available.<br />
Data Type: condition<br />
b = NULL_TERM_STRINGS<br />
Indicates if all strings shorter than their maximum length that PCFP returns to the<br />
calling program are to be null-terminated instead of space-filled. This item is typically<br />
set to TRUE by a calling program written in C. This item does not effect handling of<br />
strings the calling program inputs to PCFP; strings input to PCFP can be either<br />
null-terminated or space-filled regardless of this item.<br />
Note: Any string returned by PCFP that is at maximum length (that is, entirely fills<br />
the item containing it) is not null-terminated.<br />
Data Type: condition<br />
c = QUESTION_MARK_MATCHES_SPACE<br />
Indicates that the question mark ( ? ) wild-card character is allowed to match a space<br />
character. See 2.6 for a description of how wild-card characters can be used.<br />
WORK_AREA_SIZE<br />
Indicates the size (in words) of the work area that PCFP allocates to perform its<br />
work. The size requirements for each function are given in Sections 3 – 10 along<br />
with the description of the function. The total of WORK_AREA_SIZE and<br />
RTN_AREA_SIZE should not exceed approximately 238,000 words. As described in<br />
Sections 3 – 10, some functions have totals that are less than 238,000 words.<br />
Data Type: unsigned integer<br />
SOFTWARE_LEVEL<br />
Returns the level of PCFP software that processed the function call.<br />
Data Type: characters (8), returned<br />
GEN_DATE_TIME<br />
Returns the date and time at which the PCFP software processed the function call.<br />
Data Type: date-time, returned<br />
2–10 7830 9796–013
ERROR_CLASS<br />
Functions of PCFP<br />
Indicates what class of error, if any, occurred when PCFP attempted to process the<br />
function. In all cases, the specific nature of the special circumstance, warning, or<br />
error is given by item ERROR_CODE.<br />
Data Type: value-list, returned<br />
NONE = 0<br />
Indicates the function completed with no problems.<br />
WARNING = 1<br />
Indicates the function completed, but some special circumstance or minor<br />
problem occurred.<br />
EXECUTION_ERROR = 2<br />
Indicates that PCFP attempted the function but did not complete it because of a<br />
problem encountered during execution.<br />
CALLER_ERROR = 3<br />
Indicates that PCFP did not attempt the function because the calling program did<br />
not set up a parameter properly. This class of error typically results from a bug<br />
in the calling program.<br />
ASG_ERROR = 4<br />
ERROR_FILE<br />
Indicates that PCFP could not assign one of the specified files for some reason.<br />
Indicates which file, if any, was the source of the warning or error that PCFP<br />
encountered. If your program calls ELMS to print an error message, it should supply<br />
this value as the second numeric insert.<br />
Data Type: value-list, returned<br />
NONE = 0<br />
PCFP returns a value of NONE for this item if ERROR_CLASS = NONE, or if the<br />
error PCFP encountered is not associated with any specific file.<br />
TEMP_FILE = 1<br />
The value TEMP_FILE refers to a temporary file that PCFP may assign as part of<br />
its internal function processing.<br />
7830 9796–013 2–11
Functions of PCFP<br />
SOURCE_FILE = 2<br />
The value SOURCE_FILE refers to the source file for a copy function; it also<br />
refers to the only file for those functions that operate on a single file.<br />
DEST_FILE = 3<br />
The value DEST_FILE refers to the destination file of a copy function.<br />
SUB_ERROR_CODE<br />
Indicates the specific code (if any) associated with a warning or error that occurred<br />
when a PCFP function called another PCFP function as part of its processing and the<br />
called function (subfunction) encountered an error. The ERROR_CODE of the<br />
subfunction, without the ELMS severity code and component identifier code, is<br />
stored in SUB_ERROR_CODE. If your program calls ELMS to print error messages,<br />
it can supply this value as the third numeric insert. See Appendix A for a full<br />
description of handling SUB_ERROR_CODE using ELMS.<br />
Data Type: unsigned integer, returned<br />
ERROR_CODE<br />
Indicates the specific code associated with the warning or error that occurred while<br />
PCFP processed the function. This same value is also returned as the<br />
function-return-value in those languages (C and FORTRAN) that allow function-type<br />
procedure definitions. A value of FP_ERR_NONE (0) is returned if ERROR_CLASS =<br />
NONE. Because ERROR_CODE is an ELMS condition identifier, the calling program<br />
(if written in C) can call ELMS with this value to cause an appropriate error message<br />
to be printed.<br />
See Appendix A for a full list of the error codes that PCFP can return. See Sections<br />
11 – 13 for further information on handling error codes.<br />
Data Type: ELMS condition identifier, returned<br />
AUX_ERROR_CODE<br />
Indicates auxiliary error information (if any) associated with the error condition<br />
identified by ERROR_CODE. Typically, this value is an I/O status, an Executive<br />
request error code, or a facilities error code. For each ERROR_CODE for which<br />
AUX_ERROR_CODE is not applicable, PCFP sets AUX_ERROR_CODE to zero. If<br />
your program calls ELMS to print an error message, it should supply this value as the<br />
first numeric insert for the message.<br />
Data Type: unsigned integer, returned<br />
2–12 7830 9796–013
2.4.2. Return-Information Part of the Function Packet<br />
Functions of PCFP<br />
The return-information part of the function packet is the second part of the function<br />
packet for every PCFP function that can return repeating information. This<br />
return-information part follows immediately after the generic part.<br />
To reduce repetition, the description of this part appears once here, and is not repeated<br />
in the descriptions of the individual functions. This part of the function packet must be<br />
initialized by the calling program before calling every PCFP function that can return<br />
repeating information.<br />
The structure of this part is defined in the copy/include element FP$RTN$INFO. This<br />
element must be included in your program before any included element that defines a<br />
specific function packet that allows return information. See Figure 2–3.<br />
0<br />
1 RTN_AREA_SIZE<br />
2<br />
3 NUM_RTN_ENTRIES<br />
4<br />
5 RTN_ENTRY_SIZE NUM_ENTRIES_IN_RTN_AREA<br />
6<br />
7<br />
8<br />
Figure 2–3. Return-Information Part of the Function Packet<br />
Item Descriptions<br />
RTN_AREA_SIZE<br />
Indicates the size (in words) of the return area through which PCFP returns repeating<br />
information to the calling program. The calling program must supply a value of zero<br />
for this item if the calling program supplies no return area (that is, if the return area<br />
parameter in the argument list of the function call is null). The total of<br />
WORK_AREA_SIZE and RTN_AREA_SIZE should not exceed approximately 238,000<br />
words. As described in Sections 3 – 10, some functions have totals that are less<br />
than 238,000 words.<br />
Data Type: unsigned integer<br />
NUM_RTN_ENTRIES<br />
Indicates the total number of return entries produced by the function, including those<br />
that did not fit in the return area.<br />
Data Type: unsigned integer, returned<br />
7830 9796–013 2–13
Functions of PCFP<br />
RTN_ENTRY_SIZE<br />
Indicates the size of each return entry produced by the function. If all entries<br />
produced by the function are not the same size, this item has a value of zero.<br />
Data Type: unsigned integer, returned<br />
NUM_ENTRIES_IN_RTN_AREA<br />
Indicates the number of return entries that fit into the return area supplied by the<br />
calling program. This item is zero if PCFP placed no return entries in the return area.<br />
2.5. Work Area<br />
Data Type: unsigned integer, returned<br />
The work area is a scratch data area used by PCFP to do its calculations. The calling<br />
program does not supply this parameter. PCFP allocates and releases it dynamically. (In<br />
COBOL and FORTRAN programs, this parameter is omitted; in C programs, you must<br />
specify the NULL value for this parameter.) However, the calling program must specify<br />
the size of the work area that PCFP is to allocate. The function descriptions in Sections<br />
3 – 10 describe the work area size requirements for each function.<br />
The copy/include element for each function defines a minimum and a maximum work<br />
area size for the function. The calling program must always supply a work area no<br />
smaller in size than the minimum. The calling program can supply a work area larger<br />
than the maximum, but PCFP may not be able to use an area greater than the maximum.<br />
For a few functions, there are instances for which PCFP can use a work area larger than<br />
the defined maximum, usually to improve function performance. These exceptions are<br />
described in Sections 3 – 10. The total size of the work area and the return area should<br />
not exceed approximately 238,000 words. This is the approximate maximum size that<br />
can be specified for most PCFP functions, where the minimum relative address is<br />
MIN_DATA_ADDR and the maximum relative address is MAX_DATA_ADDR, as<br />
contained in the copy/include element FP$DEFS.<br />
2–14 7830 9796–013
2.6. Wild-Card Characters<br />
Functions of PCFP<br />
Some PCFP functions allow your program to specify partial names (for example, file<br />
names, qualifiers, element names, element versions). If you specify a partial name, any<br />
object whose name matches the partial name can qualify to be operated on by that<br />
function. You specify partial names through the use of 2 special characters, sometimes<br />
called wild-card characters. The 2 characters are<br />
• Question mark ( ? )—This character can match a single character. When the item<br />
QUESTION_MARK_MATCHES_SPACE in the generic part of the function packet is<br />
set to its default value of FALSE, the ? character matches any single character<br />
except a space character. When the item is set to TRUE, the ? character matches<br />
any single character. See 2.4.1 for a description of the<br />
QUESTION_MARK_MATCHES_SPACE item.<br />
• Asterisk ( * )—This character can match any string of zero or more characters.<br />
The following examples show how you might use these characters:<br />
• The partial name ABC?DEF matches any 7-character name starting with ABC and<br />
ending with DEF.<br />
• ABC??? matches any 6-character name starting with ABC when<br />
QUESTION_MARK_MATCHES_SPACE is FALSE. It matches any 3-character to<br />
6-character name starting with ABC when QUESTION_MARK_MATCHES_SPACE is<br />
TRUE.<br />
• A?C?E matches any 5-character name starting with A, with C in the third position,<br />
and with E in the last position.<br />
• ABC* matches any name of 3 or more characters starting with ABC.<br />
• AB*YZ matches any name of 4 or more characters starting with AB and ending with<br />
YZ.<br />
• A*56*Z matches any name of 4 or more characters starting with A, ending with Z,<br />
and with 56 somewhere in the middle.<br />
• * matches any name of any length. Typically, your program can achieve the same<br />
effect more efficiently by leaving the character string with its initial value of null.<br />
• AB??* matches any name of 4 or more characters starting with AB when<br />
QUESTION_MARK_MATCHES_SPACE is FALSE. It matches any name of 2 or more<br />
characters starting with AB when QUESTION_MARK_MATCHES_SPACE is TRUE;<br />
this would be equivalent to specifying AB*.<br />
• A?C*Z* matches any name of 4 or more characters, with A in the first position, C in<br />
the third position, and Z somewhere following the third position.<br />
• ??????* matches any name of 6 or more characters when<br />
QUESTION_MARK_MATCHES_SPACE is FALSE. It matches any name of any<br />
length when QUESTION_MARK_MATCHES_SPACE is TRUE; this would be<br />
equivalent to specifying *.<br />
7830 9796–013 2–15
Functions of PCFP<br />
The question mark character is also allowed by some functions in the name of the result<br />
object produced by that function. In such a case, the character PCFP actually places in<br />
the corresponding position of the result name is the character in the same position in the<br />
name of the input object. When the question mark character is used in this way, it can<br />
be replaced by a space character from the input object. The setting of the<br />
QUESTION_MARK_MATCHES_SPACE item does not affect this operation.<br />
This facility is most useful when a series of objects is to be created (or their names<br />
altered) using a function. As an example, you might want to change the names of all<br />
elements in a program file, so that the first 3 characters of the names are XYZ, while the<br />
remaining characters in the names are unchanged. Using the partial name XYZ?????????<br />
as the new element name accomplishes this.<br />
2.7. Function-Specific Interface Information<br />
Sections 3 – 10 define the aspects of the interface that are specific to each function.<br />
These aspects include the following:<br />
• A general description of what the function does, and what options are available.<br />
• The number and order of the parameters for the function, and the meaning of each<br />
parameter. In many cases, the parameters are described by referring to one of the<br />
general parameter categories listed in 2.1.<br />
• The name of the copy/include element associated with the function.<br />
• The physical layout and items contained in the specific part of the function packet for<br />
the function. (Note that the offsets of items in the specific part of the function<br />
packets are always shown starting at 0, even though these items are always<br />
preceded by the generic part, and in some cases, the return-information part, of the<br />
function packet.)<br />
• The INTERFACE_LEVEL to use with this function, if it is other than<br />
FP_INTERFACE_LEVEL_1.<br />
• The physical layout and items contained in each return entry (if any) that can be<br />
returned by the function.<br />
• The work area requirements of the function.<br />
2–16 7830 9796–013
2.8. Multi-Activity Programs<br />
Functions of PCFP<br />
In general, you can call PCFP functions from multiple activities running in the same<br />
program. The following are general considerations for multi-activity programs:<br />
• Each activity must have its own function packets, file identifiers, and return area.<br />
• The activity does not need to allocate a work area. PCFP is responsible for<br />
dynamically allocating the basic mode bank that is used for the work area for each<br />
activity.<br />
• The program must ensure that a file is not operated on by more than one activity.<br />
For PCFP functions that operate on more than one file (for example, COPY_ELT), the<br />
program must ensure that none of the files are operated on by another activity.<br />
Exclusive use of files does not apply to different activities of the same program and<br />
cannot be used to bypass this consideration.<br />
Special restrictions apply when calling the ACQ_FILE_INFO and ACQ_FILE_LIST<br />
functions from multi-activity programs. This is because these functions directly examine<br />
the Program Control Table (PCT), which is shared by all program activities. When<br />
multiple activities call PCFP functions, the PCT is extremely volatile during the periods<br />
when PCFP attaches internal filenames to files, assigns files to the run, and frees<br />
internal filenames and files from the run. The restrictions are as follows:<br />
• Activities that call these functions must use program-level locks to ensure that while<br />
a ACQ_FILE_INFO or ACQ_FILE_LIST function is active, no other activity is calling<br />
any PCFP function.<br />
• Similarly, while these functions are active other activities cannot make facility<br />
requests that add internal or external filenames to the run or that remove internal or<br />
external filenames from the run. Also, calls to subsystems that make facility<br />
requests should not be allowed.<br />
• If proper locking procedures are not followed, the following may result:<br />
− The functions may return a fp_err_bad_pct_name_section error, with decimal<br />
error code 2145.<br />
− A Guard Mode (IGDM) contingency may occur in bank PCFP$3.<br />
− The return information entry may contain incorrect information. The internal<br />
filename information returned in the Run Assignment Part (see 3.1.4.7) is<br />
particularly vulnerable to incorrect information.<br />
− For the ACQ_FILE_INFO function, the return information entry may be for a file<br />
different than the one specified in the file identifier.<br />
− For the ACQ_FILE_LIST function, return information entries may be returned for<br />
files that should not have been selected by function packet specifications.<br />
Conversely, return information entries may not be returned for files that should<br />
have been selected.<br />
7830 9796–013 2–17
Functions of PCFP<br />
2–18 7830 9796–013
Section 3<br />
Acquiring General File Information<br />
This section describes the following two PCFP functions that obtain directory information<br />
about one or more files:<br />
• Acquire File Information (ACQ_FILE_INFO) acquires information about a single file<br />
specified by the calling program.<br />
• Acquire File List (ACQ_FILE_LIST) acquires similar information about all files that<br />
meet selection criteria specified by the calling program.<br />
3.1. Acquire File Information (ACQ_FILE_INFO)<br />
The ACQ_FILE_INFO function returns information about a single specified file. At a<br />
minimum, this function returns to the calling program the full external identifier of the file<br />
in question, with the exception of the read and write keys that might be attached to the<br />
file. This returned information is useful if the calling program originally identified the file<br />
by means of a use name. This function returns the file identifier even for a file that does<br />
not exist (one that is neither assigned to the run nor cataloged).<br />
You can also use this function to acquire additional information about a file (for example,<br />
ownership, F-cycles, mass storage allocations, tape characteristics, and usage<br />
restrictions). The calling program indicates in the function packet which of this<br />
information PCFP returns. The full list of information obtainable by using this function is<br />
detailed under the description of the return information for this function.<br />
This function does not cause an unloaded mass storage file to be loaded.<br />
3.1.1. Parameters<br />
The ACQ_FILE_INFO function has the following parameters, each of which is described<br />
in the following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Return Information<br />
• Work Area<br />
3.1.2. Function Packet<br />
The structure of the ACQ_FILE_INFO function packet is defined in element<br />
FP$ACQFILINF. See Figure 3–1.<br />
7830 9796–013 3–1
Acquiring General File Information<br />
GENERIC PART<br />
RETURN-INFORMATION PART<br />
0 INFO_DETAIL b c d e<br />
Item Descriptions<br />
INTERFACE_LEVEL<br />
Figure 3–1. ACQ_FILE_INFO Function Packet Items<br />
Contained in the GENERIC PART of the function packet and indicates the level of the<br />
packet. The calling program should set this item to the value<br />
FP_INTERFACE_LEVEL_2. If this item is set to FP_INTERFACE_LEVEL_1, the long<br />
form return information has a format different than that described in 3.1.4 and 3.1.5.<br />
Data Type: unsigned integer<br />
INFO_DETAIL<br />
Indicates the subset of information that PCFP returns for the file.<br />
Data Type: value-list<br />
SHORT = 0<br />
Indicates that PCFP returns only the file identifier for each file.<br />
LONG = 1<br />
Indicates that PCFP returns information beyond the file identifier, including any<br />
subsets of information indicated by the items RTN_VOL_INFO,<br />
RTN_SECURITY_INFO, RTN_RUN_ASG_INFO, and RTN_EQUIP_MNEMONIC.<br />
COMPLETE = 2<br />
Indicates that PCFP returns all information obtainable through this function.<br />
When the calling program sets INFO_DETAIL to COMPLETE, the calling program<br />
receives the same information that it would receive by setting INFO_DETAIL to<br />
LONG, and RTN_VOL_INFO, RTN_SECURITY_INFO, RTN_RUN_ASG_INFO,<br />
RTN_EQUIP_MNEMONIC all to TRUE.<br />
The description of the return entry in 3.1.4 and 3.1.5 indicates the items included<br />
in each of the subsets above.<br />
b = RTN_VOL_INFO<br />
3–2 7830 9796–013
Acquiring General File Information<br />
Indicates whether the function returns volume information for the file, if the file has<br />
volume information. (Only tape files and mass storage files on removable disk can<br />
have volume information.) This item is ignored unless INFO_DETAIL = LONG.<br />
Data Type: condition<br />
c = RTN_SECURITY_INFO<br />
Indicates whether the function returns security information for the file, if the file has<br />
security information. (Only cataloged files can have security information.) This item<br />
is ignored unless INFO_DETAIL = LONG.<br />
Data Type: condition<br />
d = RTN_RUN_ASG_INFO<br />
Indicates whether the function returns run-assignment information for the file. (Only<br />
a file assigned to the run of the calling program, or given a use name by that run, can<br />
have run-assignment information.) This item is ignored unless INFO_DETAIL =<br />
LONG.<br />
Data Type: condition<br />
e = RTN_EQUIP_MNEMONIC<br />
Indicates that the function returns the equipment mnemonic for the file. This item is<br />
ignored unless INFO_DETAIL = LONG.<br />
Data Type: condition<br />
3.1.3. File Identifier<br />
The file identifier parameter names the file this function operates on. See 2.3 for a<br />
detailed description of this parameter.<br />
7830 9796–013 3–3
Acquiring General File Information<br />
3.1.4. Return Information (C Language)<br />
The structure of the return information parameter is defined in element FP$RTN$FILE.<br />
Upon successful completion of the ACQ_FILE_INFO function, PCFP creates one return<br />
entry. The contents of this return entry vary depending on what the calling program has<br />
requested in the function packet, and on the type of file the entry describes. Also, the<br />
structure of the return entry varies, depending on the language in which the calling<br />
program is written.<br />
For C programs, ACQ_FILE_INFO produces a variable-size entry, which is described<br />
next.<br />
For the variable-size form of the return entry, the size of the entry is given by the item<br />
RTN_ENTRY_SIZE in the return-information part of the function packet, and also by the<br />
item FULL_ENTRY_SIZE in the return entry itself.<br />
If the size of the return area specified by RTN_AREA_SIZE is not sufficient to contain the<br />
complete return entry, error code fp_err_small_return_area (decimal 1062) is returned in<br />
the function packet ERROR_CODE item. No information is returned, and the function<br />
packet RTN_ENTRY_SIZE and NUM_ENTRIES_IN_RTN_AREA items contain zeroes.<br />
Because various parts of this return entry are optional and not a fixed size, it is not<br />
possible for all items in the return entry to be at a fixed offset from the start of the entry.<br />
To handle this, the entry contains a number of offset items that give the offsets to the<br />
floating parts of the entry. Within each floating part, item locations are defined from the<br />
start of the part, not from the start of the entire entry. An offset value of zero indicates<br />
that the corresponding part of the entry is not present in this instance of the entry.<br />
Note: Figure 3–5 shows the new format long form information that is returned when<br />
INTERFACE_LEVEL has a value of at least FP_INTERFACE_LEVEL_2.<br />
3–4 7830 9796–013
3.1.4.1. Nonfloating Part<br />
Acquiring General File Information<br />
Following is the layout of the nonfloating part of the return entry for ACQ_FILE_INFO.<br />
As indicated in the item descriptions that follow, only words 0 – 11 are present when the<br />
calling program has set INFO_DETAIL to SHORT in the function packet. See Figure 3–2.<br />
0<br />
1 INTERFACE_LEVEL<br />
2 DIRECTORY_ID<br />
3 DIRECTORY_ID<br />
4<br />
5 QUALIFIER<br />
6<br />
7<br />
8 FILENAME<br />
9<br />
10 F_CYCLE_TYPE F_CYCLE<br />
11 b FULL_ENTRY_SIZE<br />
12 aa bb dd<br />
13 ee ff<br />
14 REL_F_CYCLE_TYPE REL_F_CYCLE<br />
15 LIFETIME ACCESS_TYPE<br />
16 EQUIP_TYPE<br />
17 EQUIP_MNEMONIC<br />
18 EQUIP_MNEMONIC<br />
Figure 3–2. Nonfloating Part of the Return Entry for C Language<br />
7830 9796–013 3–5
Acquiring General File Information<br />
Item Descriptions<br />
The initial group of items in the file return entry (words 0 – 10) is similar to the file<br />
identifier structure (see 2.3). The only difference is that the items READ_KEY and<br />
WRITE_KEY are not included. This part of the entry is always present. The locations of<br />
all items in this group are defined from the start of the entry.<br />
INTERFACE_LEVEL<br />
Has the same value as the item INTERFACE_LEVEL specified by the calling program<br />
in the function packet.<br />
Data Type: unsigned integer<br />
DIRECTORY_ID<br />
Indicates the name of the directory that contains the file. The only possible values<br />
(currently) are STD, SHARED, and null. The value null is returned for a file that is<br />
neither assigned to the run nor cataloged, and for which the Exec has not yet<br />
established the directory-id.<br />
Data Type: characters (6)<br />
QUALIFIER<br />
Indicates the qualifier for the file.<br />
Data Type: characters (12)<br />
FILENAME<br />
Indicates the basic (external) name of the file.<br />
Data Type: characters (12)<br />
F_CYCLE_TYPE<br />
Indicates if F_CYCLE contains an absolute F-cycle value or a relative F-cycle value.<br />
Data Type: value-list<br />
ABS = 1<br />
This value is returned for all files other than those described under REL.<br />
REL = 2<br />
This value is returned only for a temporary file assigned with a relative F-cycle or<br />
for a file that was identified by means of a relative F-cycle, but that is neither<br />
assigned to the run nor cataloged.<br />
3–6 7830 9796–013
F_CYCLE<br />
Acquiring General File Information<br />
Indicates the F-cycle of the file. If F_CYCLE_TYPE = ABS, this item has a value<br />
between 1 and 999 inclusive. If F_CYCLE_TYPE = REL, this item has a value<br />
between -31 and 1 inclusive.<br />
Data Type: signed integer range (-31 through 999)<br />
The following group of items (word 11) is used for navigating through the return entries.<br />
These items are present in every file return entry. These items are defined because the<br />
entries returned by a single call to this function might not all be of the same length. The<br />
locations of all items in this group are defined from the start of the entry.<br />
b = EXTENDED_INFO_PRESENT<br />
Indicates if the remaining items in the nonfloating part of this structure (words 12 to<br />
18) are present. This item is TRUE only if the calling program set INFO_DETAIL in<br />
the function packet to LONG or COMPLETE.<br />
Data Type: condition<br />
FULL_ENTRY_SIZE<br />
Indicates the word size of this entire file return entry.<br />
Data Type: unsigned integer<br />
The following group of items (words 12 and 13) gives the offsets to the nonfixed<br />
(floating) parts of the entry. These items are present only if EXTENDED_INFO_PRESENT<br />
= TRUE. If this group of items is present, it is at a fixed location in the entry; all item<br />
locations are defined from the start of the entry.<br />
All offset values in this group are given in terms of words from the start of the entry. If<br />
the offset to any part is zero, that part does not exist in the entry either because it is not<br />
applicable to the file described by this entry, or because the calling program has not<br />
requested it.<br />
aa = CAT_INFO_OFFSET<br />
Indicates the word offset from the start of the entry to the cataloged-file part of the<br />
entry.<br />
Data Type: unsigned integer<br />
bb = SECURITY_INFO_OFFSET<br />
Indicates the word offset from the start of the entry to the security part of the entry.<br />
Data Type: unsigned integer<br />
7830 9796–013 3–7
Acquiring General File Information<br />
dd = VOL_INFO_OFFSET<br />
Indicates the word offset from the start of the entry to the volume-information part<br />
of the entry.<br />
Data Type: unsigned integer<br />
ee = RUN_ASG_INFO_OFFSET<br />
Indicates the word offset from the start of the entry to the run-assignment part of<br />
the entry.<br />
Data Type: unsigned integer<br />
ff = MEDIUM_INFO_OFFSET<br />
Indicates the word offset from the start of the entry to the medium-specific part of<br />
the entry.<br />
Data Type: unsigned integer<br />
The following group of items (words 14 to 18) gives information applicable to all types of<br />
files. These items are present only if EXTENDED_INFO_PRESENT = TRUE. For this<br />
group of items, all item locations are defined from the start of the entry.<br />
REL_F_CYCLE_TYPE<br />
Indicates if REL_F_CYCLE contains a relative F-cycle value or no F-cycle value.<br />
Data Type: value-list<br />
UNSPECIFIED = 0<br />
Indicates that the file has no relative F-cycle. These cases include cataloged files<br />
in the to-be-deleted or the to-be-cataloged states, and temporary files assigned<br />
with an absolute F-cycle.<br />
REL = 2<br />
REL_F_CYCLE<br />
Indicates that the file has a relative F-cycle, and that its value is contained in<br />
REL_F_CYCLE.<br />
Indicates the relative F-cycle of the file, if REL_F_CYCLE_TYPE = REL. Otherwise, it<br />
contains zero.<br />
Data Type: signed integer range (-31 through 1)<br />
3–8 7830 9796–013
LIFETIME<br />
Indicates if the file is cataloged or temporary.<br />
Data Type: value-list<br />
NONE = 0<br />
Acquiring General File Information<br />
Indicates that the file is neither cataloged nor assigned to the run. PCFP returns<br />
this value if the file identifier that the calling program supplied refers to a file that<br />
does not exist.<br />
CATALOGED = 1<br />
Indicates that the file is cataloged.<br />
TEMPORARY = 2<br />
ACCESS_TYPE<br />
Indicates that the file is temporary.<br />
Indicates if the file is a random-access file or a sequential-access file.<br />
Data Type: value-list<br />
NONE = 0<br />
Indicates that the file is neither cataloged nor assigned to the run.<br />
RAF = 1<br />
Indicates that the file is a random-access file. (All mass storage files are<br />
random-access files.)<br />
SAF = 2<br />
Indicates that the file is a sequential-access file. (All tape files are<br />
sequential-access files.)<br />
7830 9796–013 3–9
Acquiring General File Information<br />
EQUIP_TYPE<br />
Indicates the general equipment type for the file.<br />
Data Type: value list<br />
NONE = 0<br />
Indicates the file is neither cataloged nor assigned to the run.<br />
MASS_STORAGE = 1<br />
Indicates the equipment is mass storage.<br />
TAPE = 2<br />
Indicates the equipment is tape.<br />
MISCELLANEOUS = 99<br />
Indicates that the equipment is an arbitrary device, communications line, or any<br />
other equipment falling outside the earlier categories.<br />
EQUIP_MNEMONIC<br />
Indicates the mnemonic of the specific equipment type for the file. PCFP returns a<br />
value for this item only under the following two conditions:<br />
• EQUIP_TYPE does not equal NONE<br />
• The calling program set either INFO_DETAIL = COMPLETE or<br />
RTN_EQUIP_MNEMONIC = TRUE in the function packet<br />
In instances where PCFP is unable to assign the file to determine its equipment<br />
mnemonic, PCFP fills this item with all slash characters ( / ).<br />
Data Type: characters (6)<br />
3–10 7830 9796–013
3.1.4.2. Cataloged File Part<br />
Acquiring General File Information<br />
The following group of items is present only for cataloged files, and only if the calling<br />
program has requested detailed information on the file by setting INFO_DETAIL = LONG<br />
or COMPLETE in the function packet. The location of this group of items varies within<br />
the entry, and is given by CAT_INFO_OFFSET. If CAT_INFO_OFFSET is zero, this group<br />
of items is not present. The locations of all items in this group are defined relative to the<br />
start of the group. See Figure 3–3.<br />
0<br />
1 PROJECT_ID<br />
2<br />
3<br />
4 ACCOUNT_ID<br />
5<br />
6 ASG_MNEMONIC<br />
7 ASG_MNEMONIC<br />
8 a b c d j k l m n<br />
9 ASG_STATE PRIVACY<br />
10 aa bb cc<br />
11 HIGHEST_F_CYCLE<br />
12 NUM_ASGS SITE_INFO<br />
13 CAT_DATE_TIME<br />
14<br />
15 LAST_REF_DATE_TIME<br />
16<br />
Figure 3–3. Cataloged File Part of the Return Entry for C Language<br />
Item Descriptions<br />
PROJECT_ID<br />
Indicates the project identifier for the file. This item contains all slash characters ( / )<br />
if the calling program is not privileged to see this item.<br />
Data Type: characters (12)<br />
ACCOUNT_ID<br />
Indicates the account identifier for the file. This item contains all slash characters ( / )<br />
if the calling program is not privileged to see this item.<br />
Data Type: characters (12)<br />
7830 9796–013 3–11
Acquiring General File Information<br />
ASG_MNEMONIC<br />
Indicates the type mnemonic that was specified when the file was created (with<br />
@CAT, @ASG,C or @ASG,U).<br />
Data Type: characters (6)<br />
a = DIRECTORY_DISABLED<br />
Indicates if the file is disabled due to directory error.<br />
Data Type: condition<br />
b = WRITE_DISABLED<br />
Indicates if the file is disabled because it was write-enabled and assigned to a run at<br />
the time of a system stop.<br />
Data Type: condition<br />
c = BACKUP_DISABLED<br />
Indicates if the file is disabled due to inaccessible backup.<br />
Data Type: condition<br />
d = CACHE_DISABLED<br />
Indicates if the file is disabled because it might contain noncurrent data due to cache<br />
drain failure.<br />
Data Type: condition<br />
j = GUARDED<br />
Indicates that the file was cataloged with the G option, which means that privileged<br />
runs cannot bypass protection keys.<br />
Data Type: condition<br />
k = READ_ONLY<br />
Indicates that the file has a global restriction preventing it from being updated.<br />
Data Type: condition<br />
l = WRITE_ONLY<br />
Indicates that the file has a global restriction preventing it from being read.<br />
Data Type: condition<br />
3–12 7830 9796–013
m = DELETED<br />
Acquiring General File Information<br />
Indicates that the file is marked for deletion. (The deletion occurs after all runs that<br />
have the file assigned free it.)<br />
Data Type: condition<br />
n = SYMMED<br />
Indicates if the file is on a symbiont queue.<br />
Data Type: condition<br />
ASG_STATE<br />
Indicates whether the file is currently assigned to any run, and if so, the type of the<br />
assignment.<br />
Data Type: value-list<br />
NONE = 0<br />
NON_EXCLUSIVE = 1<br />
EXCLUSIVE = 2<br />
TO_BE_CATALOGED = 3<br />
PRIVACY<br />
Indicates the privacy status for the file.<br />
Data Type: value-list<br />
PRIVATE = 1<br />
SEMIPRIVATE = 2<br />
PUBLIC = 3<br />
aa = MAX_F_CYCLES<br />
Indicates the maximum number of files that can be in the same F-cycle series as this<br />
file.<br />
Data Type: unsigned integer range (1 – 32)<br />
bb = F_CYCLE_COUNT<br />
Indicates the number of files currently in the same F-cycle series as this file.<br />
Data Type: unsigned integer range (1 – 32)<br />
7830 9796–013 3–13
Acquiring General File Information<br />
cc = F_CYCLE_RANGE<br />
Indicates the range of absolute F-cycles of files in the same F-cycle series as this file<br />
(highest absolute F-cycle minus lowest absolute F-cycle plus 1).<br />
Data Type: unsigned integer range (1 – 32)<br />
HIGHEST_F_CYCLE<br />
This is the highest absolute F-cycle of the files in the same F-cycle series as this file.<br />
Data Type: unsigned integer range (1 – 999)<br />
NUM_ASGS<br />
Indicates the number of times the file was assigned by any run since it was<br />
cataloged.<br />
Data Type: unsigned integer<br />
SITE_INFO<br />
Indicates the value of the site information field in the master file directory entry for<br />
the file. (Use this information field in any manner you choose.)<br />
Data Type: unsigned integer<br />
CAT_DATE_TIME<br />
Indicates the date and time the file was cataloged.<br />
Data Type: date-time<br />
LAST_REF_DATE_TIME<br />
Indicates the date and time the file was most recently assigned or freed (by any run).<br />
Data Type: date-time<br />
3–14 7830 9796–013
3.1.4.3. Mass Storage Part<br />
Acquiring General File Information<br />
The following group of items is present only for mass storage files, and only if the calling<br />
program has requested detailed information on the file by setting INFO_DETAIL = LONG<br />
or COMPLETE in the function packet. The location of this group of items varies within<br />
the entry, and is given by MEDIUM_INFO_OFFSET. If MEDIUM_INFO_OFFSET is zero,<br />
this group of items is not present. The locations of all items in this group are defined<br />
relative to the start of the group. See Figure 3–4.<br />
0 a b c d e f g h i j LDAT_INDEX<br />
1 ADDRESS_SIZE GRANULE_SIZE<br />
2 INIT_SIZE<br />
3 MAX_SIZE<br />
4 CURRENT_SIZE<br />
5 HIGHEST_WORD_ASGD<br />
6 HIGHEST_WORD_WRITTEN<br />
7 QUOTA_GROUP_SIZE (1)<br />
8 QUOTA_GROUP_SIZE (2)<br />
9 QUOTA_GROUP_SIZE (3)<br />
10 QUOTA_GROUP_SIZE (4)<br />
11 QUOTA_GROUP_SIZE (5)<br />
12 QUOTA_GROUP_SIZE (6)<br />
13 QUOTA_GROUP_SIZE (7)<br />
14 QUOTA_GROUP_SIZE (8)<br />
Figure 3–4. Mass Storage Part of the Return Entry for C Language<br />
Item Descriptions<br />
a = ROLLOUT_PROHIBITED<br />
Indicates that the file was cataloged with the V option, which means that a roll-out<br />
cannot unload it. (The file can, however, be unloaded explicitly.) It is always FALSE<br />
for temporary files.<br />
Data Type: condition<br />
b = BACKED_UP<br />
Indicates that the file is currently backed up. It is always FALSE for temporary files.<br />
Data Type: condition<br />
7830 9796–013 3–15
Acquiring General File Information<br />
c = UNLOADED<br />
Indicates that the file is currently unloaded. It is always FALSE for temporary files.<br />
Data Type: condition<br />
d = STORE_THROUGH<br />
Indicates that the file was cataloged with the S option, which means that its data<br />
must be written directly on nonvolatile mass storage. It is always FALSE for<br />
temporary files.<br />
Data Type: condition<br />
e = CHECKPOINTED<br />
Indicates that the file was cataloged with the B option, indicating that it is saved and<br />
reloaded as part of any full Checkpoint or Restart. It is always FALSE for temporary<br />
files.<br />
Data Type: condition<br />
f = REMOVABLE_DISK<br />
Indicates that the file resides on removable-disk mass storage.<br />
Data Type: condition<br />
g = DEVICE_PLACEMENT<br />
Indicates that the file was created using device placement.<br />
Data Type: condition<br />
h = CONTROL_UNIT_PLACEMENT<br />
Indicates that the file was created using control unit placement.<br />
Data Type: condition<br />
i = LOGICAL_PLACEMENT<br />
Indicates that the file was created using logical placement, versus absolute<br />
placement.<br />
Data Type: condition<br />
j = MULTIPLE_DEVICES<br />
Indicates that the file is spread across more than one mass storage device.<br />
Data Type: condition<br />
3–16 7830 9796–013
LDAT_INDEX<br />
Acquiring General File Information<br />
Indicates the logical device address table (LDAT) index of the mass storage device<br />
that was initially selected for the file.<br />
Data Type: unsigned integer<br />
ADDRESS_SIZE<br />
Indicates the size in words of the smallest unit of the file that can be addressed by<br />
I/O. Possible values are 1 (word-addressable files) and 28 (sector-addressable files).<br />
Data Type: unsigned integer<br />
GRANULE_SIZE<br />
Indicates the size in words of the mass storage granules allocated to the file.<br />
Possible values are 1792 (64 * 28-track granularity) and 114688<br />
(64 * 64 * 28-position granularity).<br />
Data Type: unsigned integer<br />
INIT_SIZE<br />
Indicates the size of the initial reserve of the file in words.<br />
Data Type: unsigned integer<br />
MAX_SIZE<br />
Indicates the maximum size of the file in words.<br />
Data Type: unsigned integer<br />
CURRENT_SIZE<br />
Indicates the number of words of mass storage currently allocated to the file. A<br />
value of zero implies no mass storage has been allocated to the file.<br />
Data Type: unsigned integer<br />
HIGHEST_WORD_ASSIGNED<br />
Indicates the location of the highest word of mass storage currently assigned<br />
(allocated) to the file. Words in the file are numbered starting at 0. A value of zero<br />
implies no mass storage has been allocated to the file (since mass storage is always<br />
allocated in multiples of a granule). To determine the highest granule assigned to<br />
the file, divide this value by GRANULE_SIZE and discard the remainder.<br />
Data Type: unsigned integer<br />
7830 9796–013 3–17
Acquiring General File Information<br />
HIGHEST_WORD_WRITTEN<br />
Indicates the number of the highest word of mass storage currently written in the<br />
file. Words in the file are numbered starting at 0. (Note that for cataloged files, all<br />
words in a track are considered written if at least one word in the track was written.<br />
Thus for a cataloged file, this value is always the last word of a track.) To determine<br />
the highest track written in the file, divide this value by the size of a track (1792<br />
words) and discard the remainder.<br />
Data Type: unsigned integer<br />
QUOTA_GROUP_SIZE array (1:8)<br />
3.1.4.4. Tape Part<br />
For each of the mass-storage quota groups 1 – 8, the Nth element of this array gives<br />
the number of words currently allocated to the file in the Nth quota group. The sum<br />
of the values in this array equals the value in CURRENT_SIZE.<br />
Data Type: unsigned integer<br />
The following group of items is present only for tape sequential-access files, and only if<br />
the calling program has requested detailed information on the file by setting<br />
INFO_DETAIL = LONG or COMPLETE in the function packet. The location of this group<br />
of items varies within the entry, and is given by MEDIUM_INFO_OFFSET. If<br />
MEDIUM_INFO_OFFSET is zero, this group of items is not present. The locations of all<br />
items in this group are defined relative to the start of the group. See Figure 3–5.<br />
Note: Figure 3–5 shows the new format long form of information that is returned when<br />
INTERFACE_LEVEL has a value of at least FP_INTERFACE_LEVEL_2. A new return<br />
information Tape Part definition must be used when specifying the new interface level.<br />
For C users, the new definition name is fp_rtn_file_info_tape_2_type. If you modify an<br />
existing ACQ_FILE_INFO or ACQ_FILE_LIST function to use an INTERFACE_LEVEL<br />
value of FP_INTERFACE_LEVEL_2, you must also modify the return information Tape<br />
Part definition to use the new definition name. For compatibility, the previous definition<br />
name is unchanged and describes the interface level 1 Tape Part. The format of the<br />
interface level 1 Tape Part is described in comments in the previous definition.<br />
3–18 7830 9796–013
Acquiring General File Information<br />
0 a b c d aa bb<br />
1 TAPE_CLASS RECORDING_DENSITY<br />
2 cc ee ff<br />
3 TRANSLATION_PROCESSOR_MNEMONIC<br />
4 TRANSLATION_PROCESSOR_<br />
MNEMONIC<br />
5 TRANSLATION_TAPE_MNEMONIC<br />
6 TRANSLATION_TAPE_MNEMONIC VOLUME_INDEX<br />
7 LOGICAL_FILE_POSITION<br />
8 WRITEPROTECT_INDICATOR e<br />
9 TAPE_UNIT_1_ID<br />
10 TAPE_UNIT_1_ID<br />
11 TAPE_UNIT_2_ID<br />
12 TAPE_UNIT_2_ID<br />
Figure 3–5. Tape Part of the Return Entry for C Language<br />
Item Descriptions<br />
a = LABELED<br />
Indicates that the tape file is labeled.<br />
Data Type: condition<br />
b = PARITY<br />
Indicates that the tape file is recorded with odd or even parity. This item can be<br />
EVEN only when TAPE_CLASS = SEVEN_TRACK.<br />
Data Type: value-list<br />
ODD = 0<br />
EVEN = 1<br />
c = DATA_CONVERTER<br />
If TRUE, indicates that three 8-bit bytes convert to or from four 6-bit tape characters<br />
when the tape file is written or read. This item can be TRUE only if TAPE_CLASS =<br />
SEVEN_TRACK.<br />
Data Type: condition<br />
7830 9796–013 3–19
Acquiring General File Information<br />
d = BUFFERED<br />
Indicates that data buffering applies to the tape file. This item can be TRUE only if<br />
TAPE_CLASS = HIC.<br />
Data Type: condition<br />
aa = BLOCK_NUMBERING<br />
Indicates that block numbering applies to the tape file. The three values correspond<br />
to the values BLKOFF, BLKON, and BLKOPT that can be specified when a tape file is<br />
cataloged or assigned. This item can have a value other than BLKOFF only if<br />
TAPE_CLASS = NINE_TRACK.<br />
Data Type: value-list<br />
BLKOFF = 0<br />
BLKON = 1<br />
BLKOPT = 3<br />
bb = DATA_COMPRESSION<br />
Indicates the data compression setting for the tape file. The names of the following<br />
values correspond to the data compression mnemonics that can be specified when a<br />
tape file is cataloged or assigned. Data compression values other than CMPOFF can<br />
be used only when TAPE_CLASS = NINE_TRACK or HIC.<br />
Data Type: value-list<br />
CMPOFF = 0 Data compression is off.<br />
CMPON = 1 Data compression is on.<br />
CMPOPT = 3 Data compression capable unit is required.<br />
CMP8ON = 4 Eight-bit data compression is on.<br />
CMP9ON = 5 Nine-bit data compression is on.<br />
CMPEON = 6 EDRC data compression is on.<br />
CMEOPT = 7 ERDC data compression capable unit is required.<br />
CMPLON = 8 LZ1 data compression is on.<br />
3–20 7830 9796–013
TAPE_CLASS<br />
Acquiring General File Information<br />
Indicates the general class of the tape file. The specific tape type is in item<br />
EQUIP_MNEMONIC.<br />
Data Type: value-list<br />
NINE_TRACK = 1<br />
SEVEN_TRACK = 2<br />
HIC = 3 HIC refers to half-inch cartridge.<br />
QIC = 4 QIC refers to quarter-inch cartridge.<br />
VIRTUAL = 5 A virtual tape is a simulated tape stored in a mass<br />
storage file and maintained by the Virtual Tape<br />
Handler (VTH), a Separately Packaged Exec<br />
Feature (SPEF).<br />
DVD = 6 A DVD is being processed as a simulated tape.<br />
RECORDING_DENSITY<br />
Indicates the recording density for the tape file.<br />
Data Type: value-list<br />
For all TAPE_CLASS values, the following can be returned:<br />
UNKNOWN = 0 For TAPE_CLASS = VIRTUAL and DVD, this value indicates<br />
that density does not apply. For other TAPE_CLASS values,<br />
this value indicates that density could not be determined.<br />
For TAPE_CLASS = SEVEN_TRACK, only the following values can be returned:<br />
L = 1 Density of 200 bits per inch (bpi)<br />
M = 2 Density of 556 bpi<br />
H = 3 Density of 800 bpi<br />
For TAPE_CLASS = NINE_TRACK, only the following values can be returned:<br />
H = 3 Density of 800 bpi<br />
V = 4 Density of 1,600 bpi<br />
S = 5 Density of 6,250 bpi<br />
7830 9796–013 3–21
Acquiring General File Information<br />
For TAPE_CLASS = HIC, only the following values can be returned:<br />
HICL = 6 Density of 37,871 bpi, 18-track tape<br />
HICM = 7 Density of 75,742 bpi, 36-track tape<br />
DLTM = 8 Density of 85,937 bpi, 208-track tape<br />
HISL = 9 9840 family, low density of 5,090 bpmm (bits per millimeter),<br />
288-track tape<br />
HISM = 10 9940 family, medium density, 288-track tape<br />
HISM2 = 11 9840 family, medium density, 288-track tape<br />
HISH = 12 9840 family, high density, 576-track tape<br />
T10KL = 13 T10000 family, low density,768-track tape<br />
LTO = 20 LTO family, density unknown<br />
LTO1 = 21 LTO family, density of 4,880 bpmm, 384-track tape<br />
LTO2 = 22 LTO family, density of 7,398 bpmm, 512-track tape<br />
LTO3 = 23 LTO family, density of 9,638 bpmm, 704-track tape<br />
LTO4 = 24 LTO family, density of 13,300 bpmm, 896-track tape<br />
Note: For HISM = 10, HISM2 = 11, HISH =12, and T10KL=13, the tape drive<br />
manufacturer does not provide exact density specifications.<br />
cc = BUFFERED_WRITE<br />
Indicates the buffered write mode for the tape file. The names of the following<br />
values (except DEFAULT) correspond to the tape buffering mnemonics that can be<br />
specified when a tape file is cataloged or assigned. Buffered write values other than<br />
DEFAULT and BUFOFF are returned only when TAPE_CLASS = HIC.<br />
Data type: value-list<br />
DEFAULT = 0 For TAPE_CLASS other than HIC, buffered write modes are not<br />
supported. For TAPE_CLASS = HIC, this is a cataloged file and the<br />
buffered write mode is determined by the Exec configuration<br />
parameter tape_buffering.<br />
BUFOFF = 1 All buffered write modes are disabled.<br />
BUFFON = 2 Buffered write mode is enabled for user data blocks.<br />
BUFFIL = 3 Buffered write mode is enabled for user data blocks, and for label<br />
blocks and tape marks written to labeled tapes by the Exec tape<br />
labeling system.<br />
BUFTAP = 4 Buffered write mode is enabled for user data blocks, user tape<br />
marks, and for label blocks and tape marks written to labeled tapes<br />
by the Exec tape labeling system.<br />
ee = DATA_TRANSFER_FORMAT<br />
Indicates the data transfer format for word-to-byte conversion.<br />
Data Type: value-list<br />
3–22 7830 9796–013
NONE = 0<br />
QUARTER_WORD = 1<br />
SIX_BIT = 2<br />
EIGHT_BIT = 3<br />
ff = NOISE_VALUE<br />
Acquiring General File Information<br />
Indicates the noise value for the tape file. A value of zero means that the system<br />
standard noise value is in use for this tape file.<br />
Data Type: unsigned integer range (0 – 63)<br />
TRANSLATION_PROCESSOR_MNEMONIC<br />
Indicates the mnemonic of the processor type for processor tape translation.<br />
Data Type: characters (6)<br />
TRANSLATION_TAPE_MNEMONIC<br />
Indicates the mnemonic of the tape type for processor tape translation.<br />
Data Type: characters (6)<br />
The following items are applicable only if the tape file is assigned to the run of the calling<br />
program. PCFP assigns values to these items only if the file is assigned to the run of the<br />
calling program, and the calling program has requested the return of run-assignment<br />
information (by setting either RTN_RUN_ASG_INFO = TRUE or INFO_DETAIL =<br />
COMPLETE in the function packet).<br />
VOLUME_INDEX<br />
Indicates the index of the volume at which the tape file is currently positioned. If no<br />
volume is currently mounted for the file, this value is zero.<br />
Data Type: unsigned integer<br />
LOGICAL_FILE_POSITION<br />
Indicates the position on the current volume of the logical file at which the tape file is<br />
currently positioned.<br />
Data Type: unsigned integer<br />
WRITEPROTECT_INDICATOR<br />
Indicates whether WRITEPROTECT (NORING), WRITEENABLE (RING), or neither<br />
was specified when the file was assigned to the run of the calling program.<br />
Data Type: value-list<br />
7830 9796–013 3–23
Acquiring General File Information<br />
UNSPECIFIED = 0<br />
WRITEPROTECT = 1<br />
WRITEENABLE = 2<br />
e = LOCATE_BLOCK<br />
Indicates if the tape has been positioned using the Locate Block (LBLK$) I/O<br />
function, issued either by the PCFP MOVE_SAF function or by a caller application. If<br />
TRUE, the LOGICAL_FILE_POSITION is unknown and is set to zero.<br />
Data Type: condition<br />
TAPE_UNIT_1_ID<br />
Indicates the identifier of the first (perhaps only) tape unit assigned to the file.<br />
Data Type: characters (6)<br />
TAPE_UNIT_2_ID<br />
Indicates the identifier of the second tape unit assigned to the file. If the file has<br />
only one unit assigned, this item contains null.<br />
Data Type: characters (6)<br />
3.1.4.5. Security Part<br />
The following group of items is present only for cataloged files, and only if the calling<br />
program has requested this information on the file either by setting<br />
RTN_SECURITY_INFO = TRUE and INFO_DETAIL = LONG or by setting INFO_DETAIL =<br />
COMPLETE in the function packet. The location of this group of items varies within the<br />
entry, and is given by SECURITY_INFO_OFFSET. If SECURITY_INFO_OFFSET is zero,<br />
this group of items is not present. The locations of all items in this group are defined<br />
relative to the start of the group. See Figure 3–6.<br />
0 READ_KEY<br />
1 READ_KEY<br />
2 WRITE_KEY<br />
3 WRITE_KEY<br />
4 ACR_NAME<br />
5 ACR_NAME<br />
6<br />
7 FILE_OWNER_USER_ID<br />
8<br />
9 CLEARANCE_LEVEL<br />
Figure 3–6. Security Part of Return Entry for C Language<br />
3–24 7830 9796–013
Item Descriptions<br />
READ_KEY<br />
Acquiring General File Information<br />
Indicates the read key used when assigning the file. This item contains all nulls if<br />
the file has no read key. This item contains all slash characters ( / ) if the file has a<br />
read key and the calling program is not privileged to see it.<br />
Data Type: characters (6)<br />
WRITE_KEY<br />
Indicates the write key to be used when assigning the file. This item contains all<br />
nulls if the file has no write key. This item contains all slash characters ( / ) if the file<br />
has a write key and the calling program is not privileged to see it.<br />
Data Type: characters (6)<br />
ACR_NAME<br />
Indicates the name of the access control record attached to the file. This item has a<br />
value other than null only when PRIVACY = SEMIPRIVATE.<br />
Data Type: characters (6)<br />
FILE_OWNER_USER_ID<br />
Indicates the user-id of the owner of the file.<br />
Data Type: characters (12)<br />
CLEARANCE_LEVEL<br />
3.1.4.6. Volume Part<br />
Indicates the security clearance level for the file.<br />
Data Type: unsigned integer range (0 – 63)<br />
The following group of items is present only for tape files, and for cataloged mass<br />
storage files that reside on removable disk (those for which REMOVABLE_DISK =<br />
TRUE). Also, it is present only if the calling program has requested this information on<br />
the file either by setting RTN_VOL_INFO = TRUE and INFO_DETAIL = LONG or by<br />
setting INFO_DETAIL = COMPLETE in the function packet. The location of this group of<br />
items varies within the entry, and is given by VOL_INFO_OFFSET. If<br />
VOL_INFO_OFFSET is zero, this group of items is not present. The locations of all items<br />
in this group are defined relative to the start of the group. See Figure 3–7.<br />
7830 9796–013 3–25
Acquiring General File Information<br />
0 X_WDS NUM_VOLS<br />
1 VOL_ID<br />
2 VOL_ID<br />
.. …<br />
2n-1 VOL_ID<br />
2n+1<br />
2n VOL_ID<br />
2n+2 TAPE_POOL_NAME<br />
2n+3<br />
Figure 3–7. Volume Part of the Return Entry for C Language<br />
Item Descriptions<br />
X_WDS<br />
Indicates the number of words in the volume section beyond those words occupied<br />
by VOL_ID items. These words contain a tape pool name if one exists for this file. If<br />
no tape pool name exists, this item, X_WDS, will contain a zero.<br />
Data Type: unsigned integer<br />
NUM_VOLS<br />
Indicates the number of volumes composing the tape file or the number of<br />
removable packs on which the mass storage file can reside.<br />
Data Type: unsigned integer<br />
VOL_ID array (1:n)<br />
For a tape file, this item gives the proper order of the identifiers of the volumes<br />
(reels or cartridges) composing the tape file. For a mass storage file assigned to<br />
removable packs, this item gives the identifiers of the packs on which the mass<br />
storage file can reside; in this case, the order is undefined. This array contains<br />
NUM_VOLS entries.<br />
Data Type: characters (6)<br />
TAPE_POOL_NAME<br />
When a Cartridge Tape Library (CTL) is configured and these volumes belong to a<br />
tape pool within CTL, this item will contain the name of the tape pool.<br />
Data Type: characters (12)<br />
3–26 7830 9796–013
3.1.4.7. Run Assignment Part<br />
Acquiring General File Information<br />
The following group of items is present only if the calling program has requested this<br />
information either by setting RTN_RUN_ASG_INFO = TRUE and INFO_DETAIL = LONG<br />
or by setting INFO_DETAIL = COMPLETE in the function packet. The location of this<br />
group of items varies within the entry, and is given by RUN_ASG_INFO_OFFSET. If<br />
RUN_ASG_INFO_OFFSET is zero, this group of items is not present. The locations of all<br />
items in this group are defined relative to the start of the group. See Figure 3–8.<br />
0 a b c NUM_USE_NAMES<br />
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<br />
2<br />
3 USE_NAME<br />
4<br />
3n-1<br />
3n+1<br />
.. ...<br />
3n USE_NAME<br />
Figure 3–8. Run Assignment Part of the Return Entry for C Language<br />
Item Descriptions<br />
a = ASGD_TO_RUN<br />
Indicates that the file is currently assigned to the run of the calling program.<br />
Data Type: condition<br />
b = READABLE<br />
Indicates that the file, as it is currently assigned to the run of the calling program, can<br />
be read by that run. This item is always FALSE if ASGD_TO_RUN = FALSE.<br />
Data Type: condition<br />
c = WRITEABLE<br />
Indicates that the file, as it is currently assigned to the run of the calling program, can<br />
be written to or updated by that run. This item is always FALSE if ASGD_TO_RUN =<br />
FALSE.<br />
Data Type: condition<br />
7830 9796–013 3–27
Acquiring General File Information<br />
NUM_USE_NAMES<br />
Indicates the number of internal (use) names the run of the calling program has given<br />
to this file.<br />
Data Type: unsigned integer<br />
d = ASG_OPTIONS array (1:26)<br />
Indicates the options used when the file was assigned to the run of the calling<br />
program. All items in this array are FALSE (zero) if ASGD_TO_RUN = FALSE.<br />
Data Type: condition<br />
USE_NAME array (1:n)<br />
Indicates the internal (use) name given by the run of the calling program to this file.<br />
This array contains NUM_USE_NAMES entries. The array is not present if the file<br />
does not have internal names.<br />
Data Type: characters (12)<br />
3.1.5. Return Information (COBOL and FORTRAN)<br />
The structure of the return information parameter is defined in element FP$RTN$FILE.<br />
Upon successful completion of this function, PCFP creates one return entry. The<br />
contents of this return entry vary depending on what the calling program has requested<br />
in the function packet, and on the type of file the entry describes. Also, the structure of<br />
the return entry varies, depending on the language in which the calling program is<br />
written.<br />
For COBOL and FORTRAN programs, this function produces a fixed-sized entry<br />
described in 3.1.5.1 and 3.1.5.2.<br />
If the size of the return area specified by RTN_AREA_SIZE is not sufficient to contain the<br />
complete return entry, error code fp_err_small_return_area (decimal 1062) is returned in<br />
the function packet ERROR_CODE item. No information is returned, and the function<br />
packet RTN_ENTRY_SIZE and NUM_ENTRIES_IN_RTN_AREA items contain zeroes.<br />
Note: Figure 3–11 shows the new format long form of information that is returned<br />
when INTERFACE_LEVEL has a value of at least FP_INTERFACE_LEVEL_2. A new long<br />
form return information definition must be used when specifying the new interface level.<br />
• For COBOL users, the definition name is FP-RTN-FILE-INFO-LONG-2.<br />
• For FORTRAN users, the definition name is FP$RTN$FILL2.<br />
If you modify an existing ACQ_FILE_INFO or ACQ_FILE_LIST function to use an<br />
INTERFACE_LEVEL value of FP_INTERFACE_LEVEL_2, you must also modify the long<br />
form return information definition to use the new definition name. For compatibility, the<br />
previous definition names are unchanged and describe the interface level 1 return<br />
3–28 7830 9796–013
Acquiring General File Information<br />
information. The format of the interface level 1 return information is described in the<br />
previous definition.<br />
3.1.5.1. Short Form Return Information (COBOL and FORTRAN)<br />
PCFP returns one of two fixed-size forms of the return entry described in 3.1.4 when<br />
ACQ_FILE_INFO is called from a COBOL or FORTRAN program. The short form is<br />
returned when the calling program sets INFO_DETAIL = SHORT in the function packet.<br />
Figure 3–9 shows this short form.<br />
0<br />
1 INTERFACE_LEVEL<br />
2 DIRECTORY_ID<br />
3 DIRECTORY_ID<br />
4<br />
5 QUALIFIER<br />
6<br />
7<br />
8 FILENAME<br />
9<br />
10 F_CYCLE_TYPE F_CYCLE<br />
Figure 3–9. Mass Storage Part of the Return Entry for COBOL and<br />
FORTRAN Short Form<br />
Item Descriptions<br />
Item descriptions are the same as in 3.1.4.<br />
7830 9796–013 3–29
Acquiring General File Information<br />
3.1.5.2. Long Form Return Information (COBOL and FORTRAN)<br />
The long form is returned where the calling program sets INFO_DETAIL = LONG or<br />
COMPLETE in the function packet. If a particular substructure does not apply to a file, or<br />
the calling program has not requested return of the information in that substructure,<br />
PCFP fills the entire substructure with zeros. Figure 3–10 shows the long form.<br />
When this is a mass storage file, Figure 3–10 shows the contents of words 0 through 84<br />
of the long form. When this is a tape file, Figure 3–11 shows the contents of words 34<br />
through 48 of the long form.<br />
0<br />
1 INTERFACE_LEVEL<br />
2 DIRECTORY_ID<br />
3 DIRECTORY_ID<br />
4<br />
5 QUALIFIER<br />
6<br />
7<br />
8 FILENAME<br />
9<br />
10 F_CYCLE_TYPE F_CYCLE<br />
11 a b c d e f h<br />
12 REL_F_CYCLE_TYPE REL_F_CYCLE<br />
13 LIFETIME ACCESS_TYPE<br />
14 EQUIP_TYPE<br />
15 EQUIP_MNEMONIC<br />
16 EQUIP_MNEMONIC<br />
17<br />
18 PROJECT_ID<br />
19<br />
20<br />
21 ACCOUNT_ID<br />
22<br />
23 ASG_MNEMONIC<br />
24 ASG_MNEMONIC<br />
25 a b c d j k l m n<br />
Figure 3–10. Long Form Return Entry for Mass Storage File for COBOL<br />
and FORTRAN (cont.)<br />
3–30 7830 9796–013
Acquiring General File Information<br />
26 ASG_STATE PRIVACY<br />
27 aa bb cc<br />
28 HIGHEST_F_CYCLE<br />
29 NUM_ASGS SITE_INFO<br />
30 CAT_DATE_TIME<br />
31<br />
32 LAST_REF_DATE_TIME<br />
33<br />
34 a b c d e f g h i j LDAT_INDEX<br />
35 ADDRESS_SIZE GRANULE_SIZE<br />
36 INIT_SIZE<br />
37 MAX_SIZE<br />
38 CURRENT_SIZE<br />
39 HIGHEST_WORD_ASGD<br />
40 HIGHEST_WORD_WRITTEN<br />
41 QUOTA_GROUP_SIZE (1)<br />
42 QUOTA_GROUP_SIZE (2)<br />
43 QUOTA_GROUP_SIZE (3)<br />
44 QUOTA_GROUP_SIZE (4)<br />
45 QUOTA_GROUP_SIZE (5)<br />
46 QUOTA_GROUP_SIZE (6)<br />
47 QUOTA_GROUP_SIZE (7)<br />
48 QUOTA_GROUP_SIZE (8)<br />
49 READ_KEY<br />
50 READ_KEY<br />
51 WRITE_KEY<br />
52 WRITE_KEY<br />
53 ACR_NAME<br />
54 ACR_NAME<br />
Figure 3-10. Long Form Return Entry for Mass Storage File for COBOL<br />
and FORTRAN (cont.)<br />
7830 9796–013 3–31
Acquiring General File Information<br />
55<br />
56 FILE_OWNER_USER_ID<br />
57<br />
58 CLEARANCE_LEVEL<br />
59 X_WDS NUM_VOLS<br />
60 VOL_ID (1)<br />
61 VOL_ID (1)<br />
62 VOL_ID (2)<br />
63 VOL_ID (2)<br />
64 VOL_ID (3)<br />
65 VOL_ID (3)<br />
66<br />
67 TAPE_POOL_NAME<br />
68<br />
69<br />
70<br />
71<br />
72<br />
73<br />
74 a b c NUM_USE_NAMES<br />
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<br />
76<br />
77 USE_NAME (1)<br />
78<br />
79<br />
80 USE_NAME (2)<br />
81<br />
82<br />
83 USE_NAME (3)<br />
84<br />
Figure 3–10. Long Form Return Entry for Mass Storage File for COBOL<br />
and FORTRAN<br />
3–32 7830 9796–013
Acquiring General File Information<br />
34 a b c d aa bb<br />
35 TAPE_CLASS RECORDING_DENSITY<br />
36 cc ee ff<br />
37 TRANSLATION_PROCESSOR_MNEMONIC<br />
38 TRANSLATION_PROCESSOR_<br />
MNEMONIC<br />
39 TRANSLATION_TAPE_MNEMONIC<br />
40 TRANSLATION_TAPE_MNEMONIC VOLUME_INDEX<br />
41 LOGICAL_FILE_POSITION<br />
42 WRITEPROTECT_INDICATOR e<br />
43 TAPE_UNIT_1_ID<br />
44 TAPE_UNIT_1_ID<br />
45 TAPE_UNIT_2_ID<br />
46 TAPE_UNIT_2_ID<br />
47<br />
48<br />
Figure 3–11. Long Form Tape Part of the Return Entry for COBOL and<br />
FORTRAN<br />
7830 9796–013 3–33
Acquiring General File Information<br />
Item Descriptions<br />
INTERFACE_LEVEL (word 1) through F_CYCLE (word 10) are the same as the<br />
corresponding items described in 3.1.4.1. These items are always present.<br />
Word 11<br />
a = EXTENDED_INFO_PRESENT<br />
Indicates whether the items REL_F_CYCLE_TYPE through EQUIP_MNEMONIC<br />
(words 12 – 16) contain valid values. These items are defined in 3.1.4.1.<br />
Data Type: condition<br />
b = CAT_INFO_PRESENT<br />
Indicates whether the items PROJECT_ID through LAST_REF_DATE_TIME (words<br />
17 – 33) that describe a cataloged file contain valid values. These items are defined<br />
in 3.1.4.2.<br />
Data Type: condition<br />
c = MASS_STORAGE_INFO_PRESENT<br />
Indicates whether the items that describe a mass storage file<br />
(ROLLOUT_PROHIBITED through QUOTA_GROUP_SIZE, words 34 – 48 in<br />
Figure 3–10) contain valid values. These items are defined in 3.1.4.3.<br />
Data Type: condition<br />
d = TAPE_INFO_PRESENT<br />
Indicates whether the items that describe a tape file (LABELED through<br />
TAPE_UNIT_2_ID, words 34 – 48 in Figure 3–11) contain valid values. These items<br />
are defined in 3.1.4.4. Note that these items overlay those that describe a mass<br />
storage file, and that MASS_STORAGE_INFO_PRESENT and TAPE_INFO_PRESENT<br />
cannot both be TRUE.<br />
Data Type: condition<br />
e = SECURITY_INFO_PRESENT<br />
Indicates whether the items READ_KEY through CLEARANCE_LEVEL (words 49 –<br />
58) that describe the security characteristics of the file contain valid values. These<br />
items are defined in 3.1.4.5.<br />
Data Type: condition<br />
3–34 7830 9796–013
f = VOL_INFO_PRESENT<br />
Acquiring General File Information<br />
Indicates whether the items NUM_VOLS through VOL_ID (words 59 – 65) that<br />
describe the volumes of the file contain valid values. These items are defined in<br />
3.1.4.6. Note that if the file has more than three volumes, only the identifiers of the<br />
first three are returned, although NUM_VOLS contains the total number for the file.<br />
Data Types: condition<br />
h = RUN_ASG_INFO_PRESENT<br />
Indicates whether the items ASGD_TO_RUN through USE_NAME (words 74 – 84)<br />
that describe how the file is assigned to the run of the calling program contain valid<br />
values. These items are defined in 3.1.4.7. Note that if the file has more than three<br />
internal names attached, only three are returned, although NUM_USE_NAMES<br />
contains the total number for the file.<br />
Data Types: condition<br />
Words 12 – 16 See the description of words 14 – 18 in 3.1.4.1.<br />
Words 17 – 33 See 3.1.4.2.<br />
Words 34 – 48 If this is a mass storage file, see Figure 3–10 and 3.1.4.3.<br />
Words 49 – 58 See 3.1.4.5.<br />
Words 59 – 68 See 3.1.4.6.<br />
If this is a tape file, see Figure 3–11 and 3.1.4.4.<br />
Words 69 – 73 Unused and always contain zero.<br />
Words 74 – 84 See 3.1.4.7.<br />
3.1.6. Work Area<br />
ACQ_FILE_INFO requires 1,000 words for its work area. There is one special situation in<br />
which 1,000 words is insufficient for this function. If the file being examined has more<br />
than 160 internal (@USE) names attached, this function requires an additional 5 words of<br />
work area for each internal name in excess of 160.<br />
The total of WORK_AREA_SIZE and RTN_AREA_SIZE should not exceed approximately<br />
205,000 words. This is the approximate maximum size that can be specified for this<br />
function, where the minimum relative address is MIN_DATA_ADDR and the maximum<br />
relative address is MAX_DATA_ADDR_WITH_PCT, as contained in the copy/include<br />
element FP$DEFS.<br />
7830 9796–013 3–35
Acquiring General File Information<br />
3.2. Acquire File List (ACQ_FILE_LIST)<br />
ACQ_FILE_LIST acquires directory information about one or more files that meet<br />
conditions specified by the calling program. At a minimum, this function returns to the<br />
calling program the external identifiers of all files that are selected (with the exception of<br />
the read and write keys). The file identifiers are returned in a form usable as input to<br />
other functions that operate on files. Thus, if a program must perform an operation on all<br />
files that meet some conditions, it can call this function first to obtain the identifiers of all<br />
the files meeting the conditions, then repeatedly call the appropriate function to perform<br />
the operation on each file identifier returned.<br />
The calling program can select files based on a number of attributes. The attributes are<br />
described in 3.2.2. Each attribute for which a value is supplied further restricts the set of<br />
files that is selected. The calling program may supply values for as few or as many of<br />
these attributes as it requires.<br />
When this function selects a list of files, it assumes no default selection criteria. Unless<br />
the calling program explicitly specifies a particular attribute, this function assumes that all<br />
values of that attribute qualify. This means, for example, that the calling program must<br />
specify a directory-id if it must limit the search to a specific directory.<br />
This function returns all the same information as that returned by ACQ_FILE_INFO. See<br />
3.1.4 and 3.1.5 for the full description of this information. As with the ACQ_FILE_INFO<br />
function, this function provides a means for returning only selected subsets of the full<br />
set of attributes to the calling program. The composition of these subsets is given in<br />
3.1.4 and 3.1.5. Also, as with ACQ_FILE_INFO, the operating system may mask certain<br />
of the returned attributes for security purposes.<br />
3.2.1. Parameters<br />
The ACQ_FILE_LIST function has the following parameters, each of which is described<br />
in the following subsections:<br />
• Function Packet<br />
• Return Information<br />
• Work Area<br />
3–36 7830 9796–013
3.2.2. Function Packet<br />
Acquiring General File Information<br />
The structure of the ACQ_FILE_LIST function packet is defined in element<br />
FP$ACQFILLST. See Figure 3–12.<br />
GENERIC PART<br />
RETURN-INFORMATION PART<br />
0 INFO_DETAIL b c d e<br />
1 SEARCH_SET LIFETIME<br />
2<br />
3<br />
4 DIRECTORY_ID<br />
5 DIRECTORY_ID<br />
6<br />
7 QUALIFIER<br />
8<br />
9<br />
10 FILENAME<br />
11<br />
12 PACK_ID<br />
13 PACK_ID<br />
14 MIN_F_CYCLE_TYPE MIN_F_CYCLE<br />
15 MAX_F_CYCLE_TYPE MAX_F_CYCLE<br />
16<br />
17 PROJECT_ID<br />
18<br />
19<br />
20 ACCOUNT-ID<br />
21<br />
Figure 3–12. ACQ_FILE_LIST Function Packet Items (cont.)<br />
22 ACR_NAME<br />
7830 9796–013 3–37
Acquiring General File Information<br />
23 ACR_NAME<br />
24<br />
25 FILE_OWNER_USER_ID<br />
26<br />
27 MIN_CLEARANCE_LEVEL<br />
28 MAX_CLEARANCE_LEVEL<br />
29 MIN_CAT_DATE_TIME<br />
30<br />
31 MAX_CAT_DATE_TIME<br />
32<br />
33 MIN_LAST_REF_DATE_TIME<br />
34<br />
35 MAX_LAST_REF_DATE_TIME<br />
36<br />
37<br />
38<br />
39<br />
40<br />
41 EQUIP_TYPE f SITE_INFO<br />
42 NUM_SELECTED<br />
43<br />
44<br />
45<br />
46<br />
Item Descriptions<br />
INTERFACE_LEVEL<br />
Figure 3–12. ACQ_FILE_LIST Function Packet Items<br />
Contained in the GENERIC PART of the function packet and indicates the level of the<br />
packet. The calling program should set this item to the value<br />
FP_INTERFACE_LEVEL_2. If this item is set to FP_INTERFACE_LEVEL_1, the long<br />
form return information has a format different than that described in 3.1.4 and 3.1.5.<br />
Data Type: unsigned integer<br />
INFO_DETAIL<br />
3–38 7830 9796–013
Acquiring General File Information<br />
For each individual file selected by this function, indicates what subset of information<br />
PCFP returns.<br />
Data Type: value-list<br />
SHORT = 0<br />
Indicates that PCFP returns only the file identifier for each file.<br />
LONG = 1<br />
Indicates that PCFP returns information beyond the file identifier, including any<br />
subsets of information indicated by the items RTN_VOL_INFO,<br />
RTN_SECURITY_INFO, RTN_RUN_ASG_INFO and RTN_EQUIP_MNEMONIC.<br />
(The description of the return entry in 3.1.4 indicates the items included.)<br />
COMPLETE = 2<br />
Indicates that PCFP returns all information obtainable through this function.<br />
When the calling program sets INFO_DETAIL to COMPLETE, the calling program<br />
receives the same information it would receive by setting INFO_DETAIL to<br />
LONG, and RTN_VOL_INFO, RTN_SECURITY_INFO, RTN_RUN_ASG_INFO,<br />
RTN_EQUIP_MNEMONIC all to TRUE.<br />
b = RTN_VOL_INFO<br />
Indicates whether the function returns volume information for each file selected by<br />
the function that has volume information. (Only tape files and mass storage files on<br />
removable disk can have volume information.) This item is ignored unless<br />
INFO_DETAIL = LONG.<br />
Data Type: condition<br />
c = RTN_SECURITY_INFO<br />
Indicates whether the function returns security information for each cataloged file<br />
selected by the function that has security information. This item is ignored unless<br />
INFO_DETAIL = LONG.<br />
Data Type: condition<br />
d = RTN_RUN_ASG_INFO<br />
Indicates whether the function returns run-assignment information for each file<br />
selected by the function. This item is ignored unless INFO_DETAIL = LONG.<br />
Data Type: condition<br />
7830 9796–013 3–39
Acquiring General File Information<br />
e = RTN_EQUIP_MNEMONIC<br />
Indicates whether the function returns the equipment mnemonic for each file<br />
selected by the function. This item is ignored unless INFO_DETAIL = LONG.<br />
Data Type: condition<br />
SEARCH_SET<br />
Indicates which basic set of files PCFP considers for selection by this function.<br />
Data Type: value-list<br />
ASGD_TO_RUN = 1<br />
This value indicates that the files to be considered are those assigned to the run<br />
of the calling program.<br />
KNOWN_TO_RUN = 2<br />
This value indicates that the files to be considered are those assigned to the run<br />
of the calling program and to which an internal (@USE) name has been attached<br />
by that run.<br />
CATALOG_DIRECTORY = 3<br />
LIFETIME<br />
This value indicates that the files to be considered are those contained within<br />
the cataloged file directory(s) indicated by DIRECTORY_ID. When the calling<br />
program specifies this value, it must also specify both QUALIFIER and<br />
FILENAME and must not include masking characters in these values.<br />
Indicates whether the files to be selected must be cataloged, temporary, or either.<br />
Data Type: value-list<br />
NO_CONSTRAINT = 0<br />
CATALOGED = 1<br />
TEMPORARY = 2<br />
Note that if LIFETIME = TEMPORARY and SEARCH_SET = CATALOG_DIRECTORY,<br />
no files can be selected by the function.<br />
DIRECTORY_ID<br />
Indicates the name of the directory from which files are to be selected. The only<br />
legal values (currently) are STD and SHARED; a null value indicates that this function<br />
is to select files without regard to directory-id.<br />
Data Type: characters (6)<br />
3–40 7830 9796–013
QUALIFIER<br />
Acquiring General File Information<br />
Indicates the qualifier or pattern of the qualifier of the files this function selects.<br />
Unless the calling program set SEARCH_SET = CATALOG_DIRECTORY, the value<br />
the calling program supplies for this item may contain the question mark ( ? ) and the<br />
asterisk ( * ) wild-card characters as described in 2.6. A null value indicates that this<br />
function selects files without regard to qualifier.<br />
Data Type: characters (12)<br />
FILENAME<br />
Indicates the name or pattern of the name of the files this function selects. This<br />
value is compared only against the intrinsic (external) file name; it is never compared<br />
to an internal name that the run of the calling program might have attached. Unless<br />
the calling program set SEARCH_SET = CATALOG_DIRECTORY, the value the<br />
calling program supplies for this item may contain the question mark ( ? ) and the<br />
asterisk ( * ) wild-card characters as described in 2.6. A null value indicates that this<br />
function selects files without regard to file name.<br />
Data Type: characters (12)<br />
PACK_ID<br />
Indicates the removable pack from which the files are selected. A null value<br />
indicates that this function selects files without regard to the removable pack on<br />
which they reside.<br />
Data Type: characters (6)<br />
MIN_F_CYCLE_TYPE<br />
Indicates whether MIN_F_CYCLE contains an absolute F-cycle value, a relative<br />
F-cycle value, or no F-cycle value.<br />
Data Type: value-list<br />
UNSPECIFIED = 0<br />
Indicates that this function selects files without regard to a minimum F-cycle.<br />
ABS = 1<br />
Indicates that this function limits the files it selects to those with an absolute<br />
F-cycle greater than or equal to MIN_F_CYCLE. Files with no absolute F-cycle<br />
are not selected.<br />
REL = 2<br />
Indicates that this function limits the files it selects to those with a relative<br />
F-cycle greater than or equal to MIN_F_CYCLE. Files with no relative F-cycle are<br />
not selected.<br />
7830 9796–013 3–41
Acquiring General File Information<br />
MIN_F_CYCLE<br />
Indicates the minimum F-cycle of the files this function selects. (Files with a lower<br />
F-cycle are not selected.) If MIN_F_CYCLE_TYPE = UNSPECIFIED, this item must<br />
have value 0. If MIN_F_CYCLE_TYPE = ABS, this item must have a value between 1<br />
and 999 inclusive. If MIN_F_CYCLE_TYPE = REL, this item must have a value<br />
between -31 and 1 inclusive.<br />
Data Type: signed integer range (-31 through 999)<br />
MAX_F_CYCLE_TYPE<br />
Indicates whether MAX_F_CYCLE contains an absolute F-cycle value, a relative<br />
F-cycle value, or no F-cycle value.<br />
Data Type: value-list<br />
UNSPECIFIED =0<br />
Indicates that this function selects files without regard to a maximum F-cycle.<br />
ABS = 1<br />
Indicates that this function limits the files it selects to those with an absolute<br />
F-cycle less than or equal to MAX_F_CYCLE. Files with no absolute F-cycle are<br />
not selected.<br />
REL = 2<br />
Indicates that this function limits the files it selects to those with a relative<br />
F-cycle less than or equal to MAX_F_CYCLE. Files with no relative F-cycle are<br />
not selected.<br />
If the calling program set MIN_F_CYCLE_TYPE = REL, it cannot set<br />
MAX_F_CYCLE_TYPE = ABS, and vice versa.<br />
MAX_F_CYCLE<br />
Indicates the maximum F-cycle of the files this function selects. (Files with a higher<br />
F-cycle are not selected.) If MAX_F_CYCLE_TYPE = UNSPECIFIED, this item must<br />
have value 0. If MAX_F_CYCLE_TYPE = ABS, this item must have a value between<br />
1 and 999 inclusive. If MAX_F_CYCLE_TYPE = REL, this item must have a value<br />
between -31 and 1 inclusive.<br />
Data Type: signed integer range (-31 through 999)<br />
3–42 7830 9796–013
PROJECT_ID<br />
Acquiring General File Information<br />
Indicates the project-id or pattern of project-id of the files this function selects. The<br />
value the calling program supplies for this item may include the question mark ( ? )<br />
and the asterisk ( * ) wild-card characters as described in 2.6. A value of all slashes<br />
( / ) limits the files selected to those whose project-id the run of the calling program<br />
is not privileged to see. A null value for this item indicates that this function selects<br />
files without regard to project-id.<br />
Data Type: characters (12)<br />
ACCOUNT_ID<br />
Indicates the account identifier or pattern of account identifier of the files this<br />
function selects. The value the calling program supplies for this item may include<br />
the question mark ( ? ) and the asterisk ( * ) wild-card characters as described in 2.6.<br />
A value of all slashes ( / ) limits the files selected to those whose account identifier<br />
the run of the calling program is not privileged to see. A null value for this item<br />
indicates that this function selects files without regard to account identifier.<br />
Data Type: characters (12)<br />
ACR_NAME<br />
Indicates the name or pattern of the name of the access control record (ACR)<br />
attached to the files this function selects. The value the calling program supplies for<br />
this item may include the question mark ( ? ) and the asterisk ( * ) wild-card<br />
characters as described in 2.6. A null value for this item indicates that this function<br />
selects files without regard to access control record.<br />
Data Type: characters (6)<br />
FILE_OWNER_USER_ID<br />
Indicates the user-id of the owner or pattern of the user-id of the owner of the files<br />
this function selects. The value the calling program supplies for this item may<br />
include the question mark ( ? ) and the asterisk ( * ) wild-card characters as described<br />
in 2.6. A null value for this item indicates that this function selects files without<br />
regard to owner user-id.<br />
Data Type: characters (12)<br />
MIN_CLEARANCE_LEVEL<br />
Indicates the minimum clearance level for the files this function selects. A value of<br />
zero indicates that this function selects files without regard to a minimum clearance<br />
level.<br />
Data Type: unsigned integer, range (0 – 63)<br />
7830 9796–013 3–43
Acquiring General File Information<br />
MAX_CLEARANCE_LEVEL<br />
Indicates the maximum clearance level for the files this function selects. A value of<br />
zero indicates that this function selects the files without regard to a maximum<br />
clearance level.<br />
Data Type: unsigned integer, range (0 – 63)<br />
MIN_CAT_DATE_TIME<br />
Indicates the earliest date and time at which the files this function selects were<br />
cataloged. A value of zero indicates that this function selects files without regard to<br />
a minimum date and time of creation.<br />
Data Type: date-time<br />
MAX_CAT_DATE_TIME<br />
Indicates the latest date and time at which the files this function selects were<br />
cataloged. A value of zero indicates that this function selects files without regard to<br />
a maximum date and time of creation.<br />
Data Type: date-time<br />
MIN_LAST_REF_DATE_TIME<br />
Indicates the earliest date and time at which the files this function selects were<br />
most recently referenced (assigned). A value of zero indicates that this function<br />
selects files without regard to a minimum date and time of reference.<br />
Data Type: date-time<br />
MAX_LAST_REF_DATE_TIME<br />
Indicates the latest date and time at which the files this function selects were most<br />
recently referenced. A value of zero indicates that this function selects files without<br />
regard to a maximum date and time of reference.<br />
Data Type: date-time<br />
3–44 7830 9796–013
EQUIP_TYPE<br />
Acquiring General File Information<br />
Indicates the general equipment type that the files this function selects must have.<br />
A value of NONE indicates that this function selects files without regard to<br />
equipment type.<br />
Data Type: value-list<br />
NONE = 0<br />
MASS_STORAGE =1<br />
TAPE = 2<br />
MISCELLANEOUS = 99<br />
The value MISCELLANEOUS refers to arbitrary devices, communications lines, and<br />
other equipment not covered by the earlier categories.<br />
f = SELECT_ON_SITE_INFO<br />
If TRUE, this function selects only files that have site information in the master file<br />
directory that matches the value the calling program specified in SITE_INFO. (The<br />
site-information field can be used by a site in any manner it chooses.)<br />
Data Type: condition<br />
SITE_INFO<br />
If SELECT_ON_SITE_INFO = TRUE, this item gives the value of the site information<br />
that PCFP must match. If SELECT_ON_SITE_INFO = FALSE, this item must contain<br />
zero.<br />
Data Type: half word unsigned integer<br />
NUM_SELECTED<br />
Indicates how many files this function selected.<br />
Data Type: unsigned integer, returned<br />
7830 9796–013 3–45
Acquiring General File Information<br />
3.2.3. Return Information<br />
The return information parameter produces one return entry for each file it selects. The<br />
format of this return entry is identical to that produced by the function ACQ_FILE_INFO,<br />
and is described in 3.1.4 for calling programs written in C and in 3.1.5 for calling<br />
programs written in COBOL and FORTRAN.<br />
Note: Subsections 3.1.4.4 and 3.1.5 describe the new format long form information<br />
that is returned when INTERFACE_LEVEL has a value of at least<br />
FP_INTERFACE_LEVEL_2. A new long form return information definition must be used<br />
when specifying the new interface level.<br />
• For C users, the definition name is fp_rtn_file_info_tape_2_type.<br />
• For COBOL users, the definition name is FP-RTN-FILE-INFO-LONG-2.<br />
• For FORTRAN users, the definition name is FP$RTN$FILL2.<br />
If you modify an existing ACQ_FILE_LIST function to use an INTERFACE_LEVEL value of<br />
FP_INTERFACE_LEVEL_2, you must also modify the long form return information<br />
definition to use the new definition name. For compatibility, the previous definition<br />
names are unchanged and describe the interface level 1 return information. The format<br />
of the interface level 1 return information is described in comments in the previous<br />
definitions.<br />
The contents of each return entry produced by this function vary depending on what the<br />
calling program has specified in the function packet, and on the type of file the entry<br />
describes. For a calling program written in C, all entries produced by a single call to this<br />
function are not necessarily the same size. When all entries are the same size, the size<br />
is given by the item RTN_ENTRY_SIZE in the GENERIC PART of the function packet.<br />
When the entries differ in size, RTN_ENTRY_SIZE has a value of zero. In either case, the<br />
item FULL_ENTRY_SIZE in each return entry gives the size of that return entry.<br />
Unlike other PCFP functions that return repeating information, the ACQ_FILE_LIST<br />
function does not continue processing once it determines that a return entry will not fit<br />
in the return area. In this case, it immediately returns the error code<br />
fp_err_small_return_area (decimal1062) in the function packet ERROR_CODE item. The<br />
NUM_RTN_ENTRIES item will be one greater than the NUM_ENTRIES_IN_RTN_AREA<br />
item.<br />
3–46 7830 9796–013
3.2.4. Work Area<br />
Acquiring General File Information<br />
The following definitions indicate the work area requirement (in words) for the<br />
ACQ_FILE_LIST function:<br />
• The size of the work area must always be at least 1,000 words.<br />
• When SEARCH_SET = CATALOG_DIRECTORY, the minimum space requirement<br />
(1,000 words) is always sufficient.<br />
• When SEARCH_SET = ASGD_TO_RUN or KNOWN_TO_RUN, the approximate<br />
words of space required is given by the following formula:<br />
(200 + 15 * E +7 * I)<br />
where:<br />
E is the total number of external files known to the run. An external file is<br />
known to the run if it is assigned or if it has an internal name attached.<br />
I is the total number of internal (@USE) names assigned to the run.<br />
The minimum work area of 1,000 words, for example, is adequate for a run with 40<br />
external files and 28 internal file names. The maximum work space of 5,000 words is<br />
adequate, for example, for a run with 180 external files and 300 internal file names or for<br />
a run with 250 external files and 150 internal file names.<br />
The total of WORK_AREA_SIZE and RTN_AREA_SIZE should not exceed approximately<br />
205,000 words. This is the approximate maximum size that can be specified for this<br />
function, where the minimum relative address is MIN_DATA_ADDR and the maximum<br />
relative address is MAX_DATA_ADDR_WITH_PCT, as contained in the copy/include<br />
element FP$DEFS.<br />
7830 9796–013 3–47
Acquiring General File Information<br />
3–48 7830 9796–013
Section 4<br />
Changing File Attributes<br />
This section describes the following five PCFP functions that change the characteristics<br />
of a specified file or a specified F-cycle series of files that have been cataloged.<br />
• Change File Specific Attributes (CHG_FILE) changes directory attributes that apply to<br />
a single specified file.<br />
• Change File Cycle (CHG_FILE_CYC) changes the F-cycle limit associated with a<br />
specified F-cycle series of files.<br />
• Change File Security (CHG_FILE_SEC) changes security attributes that apply to all<br />
files of a specified F-cycle series of files.<br />
• Change File Keys (CHG_FILE_KEYS) changes the read key and/or write key<br />
associated with all files of a specified F-cycle series of files.<br />
• Change File Name (CHG_FILE_NAME) changes the qualifier and/or file name<br />
associated with all files of a specified F-cycle series of files.<br />
4.1. Change File Specific Attributes (CHG_FILE)<br />
The CHG_FILE function changes directory attributes that apply to a single file specified<br />
by the calling program. For a cataloged file, this function can change any or all of the<br />
following file attributes:<br />
• Project-id<br />
• Account-id<br />
• Rollout-prohibited indicator (V option)<br />
• Read-only/write-only restrictions on the file<br />
• Disable statuses of file (that is, it can enable or disable a file)<br />
• Site information<br />
The CHG_FILE function can also be used to change an empty, sector-addressable,<br />
temporary, or cataloged mass storage file to a program file. The caller must have read<br />
and write access to the file. This is the only case with any of the change file functions<br />
described in this section where the file contents are changed. All other change file<br />
functions change only directory attributes. This is also the only case where a change file<br />
function can operate on a temporary file.<br />
7830 9796–013 4–1
Changing File Attributes<br />
Note that for a temporary file, the file attribute change options listed above are not<br />
available. The CHG_FILE function has the following program file initialization options:<br />
• Initialize the file as a PF, LPF, standard LEPF, or large LEPF.<br />
• Require PCFP to assign the file exclusively or not.<br />
4.1.1. Parameters<br />
The CHG_FILE function has the following parameters, each of which is described in the<br />
following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Work Area<br />
4.1.2. Function Packet<br />
The structure of the function packet for CHG_FILE is defined in element FP$CHGFIL.<br />
See Figure 4–1.<br />
0<br />
GENERIC PART<br />
1 PROJECT_ID<br />
2<br />
3<br />
4 ACCOUNT_ID<br />
5<br />
6 ROLLOUT_PROHIBITED INIT_PROGRAM_FILE<br />
7 DIRECTORY_DISABLE WRITE_DISABLE<br />
8 BACKUP_DISABLE CACHE_DISABLE<br />
9 READ_ONLY WRITE_ONLY<br />
10 a B SITE_INFO<br />
Figure 4–1. CHG_FILE Function Packet Items<br />
4–2 7830 9796–013
Item Descriptions<br />
PROJECT_ID<br />
Changing File Attributes<br />
Indicates the new project-id for the file. The characters composing this value must<br />
be from the set A – Z, 0 – 9, hyphen ( - ), and dollar sign ($). A null value indicates<br />
that PCFP is not to change the project-id of the file.<br />
Data Type: characters (12)<br />
ACCOUNT_ID<br />
Indicates the new account-id for the file125<br />
The characters composing this value must be from the set A – Z, 0 – 9, period ( . ),<br />
and hyphen ( - ). A null value indicates that PCFP is not to change the account-id of<br />
the file.<br />
Data Type: characters (12)<br />
ROLLOUT_PROHIBITED<br />
Indicates how PCFP is to change the rollout-prohibited indicator (V option) for the file.<br />
Data Type: value-list<br />
NO_CHG = 0<br />
Causes no change to this indicator.<br />
SET_OFF = 1<br />
Turns off this indicator, regardless of its previous setting.<br />
SET_ON = 2<br />
Turns on this indicator, regardless of its previous setting.<br />
INIT_PROGRAM_FILE<br />
Indicates if PCFP should initialize the file as a program file.<br />
Data Type: value-list<br />
NONE = 0<br />
PF = 1<br />
Causes no file initialization.<br />
Initialize the file as a standard program file (PF).<br />
7830 9796–013 4–3
Changing File Attributes<br />
LPF = 2<br />
Initialize the file as a large program file (LPF).<br />
STANDARD_LEPF = 3<br />
Initialize the file as a standard capacity, large element program file (standard<br />
LEPF).<br />
LARGE_LEPF = 4<br />
Initialize the file as a large capacity, large element program file (large LEPF).<br />
For values other than NONE, the file must be an empty, sector-addressable, temporary,<br />
or cataloged mass storage file to which the caller has read and write access. Files are<br />
empty when they are initially created with @ASG or @CAT and when they are erased<br />
with the PCFP ERS_RAF function of the FURPUR @ERS command.<br />
DIRECTORY_DISABLE<br />
Indicates how PCFP is to change the directory-disabled indicator for the file.<br />
Data Type: value-list<br />
NO_CHG = 0<br />
Causes no change to this indicator.<br />
SET_OFF = 1<br />
Turns off this indicator, regardless of its previous setting.<br />
SET_ON = 2<br />
Turns on this indicator, regardless of its previous setting.<br />
WRITE_DISABLE<br />
Indicates how PCFP changes the write-disabled indicator for the file.<br />
Data Type: value-list<br />
NO_CHG = 0<br />
Causes no change to this indicator.<br />
SET_OFF = 1<br />
Turns off this indicator, regardless of its previous setting.<br />
4–4 7830 9796–013
SET_ON = 2<br />
Turns on this indicator, regardless of its previous setting.<br />
BACKUP_DISABLE<br />
Indicates how PCFP changes the backup-disabled indicator for the file.<br />
Data Type: value-list<br />
NO_CHG = 0<br />
Causes no change to this indicator.<br />
SET_OFF = 1<br />
Turns off this indicator, regardless of its previous setting.<br />
SET_ON = 2<br />
Turns on this indicator, regardless of its previous setting.<br />
CACHE_DISABLE<br />
Indicates how PCFP changes the cache-disabled indicator for the file.<br />
Data Type: value-list<br />
NO_CHG = 0<br />
Causes no change to this indicator.<br />
SET_OFF = 1<br />
Turns off this indicator, regardless of its previous setting.<br />
SET_ON = 2<br />
READ_ONLY<br />
Turns on this indicator, regardless of its previous setting.<br />
Changing File Attributes<br />
Indicates how PCFP changes the read-only indicator (R-option) for the file.<br />
Data Type: value-list<br />
NO_CHG = 0<br />
Causes no change to this indicator.<br />
7830 9796–013 4–5
Changing File Attributes<br />
SET_OFF = 1<br />
Turns off this indicator, regardless of its previous setting.<br />
SET_ON = 2<br />
WRITE_ONLY<br />
Turns on this indicator, regardless of its previous setting.<br />
Indicates how PCFP changes the write-only indicator (W-option) for the file.<br />
Data Type: value-list<br />
NO_CHG = 0<br />
Causes no change to this indicator.<br />
SET_OFF = 1<br />
Turns off this indicator, regardless of its previous setting.<br />
SET_ON = 2<br />
Turns on this indicator, regardless of its previous setting.<br />
a = CHG_SITE_INFO<br />
Indicates that PCFP changes the site-information field in the master file directory<br />
entry for the file. The new value is given by SITE_INFO. (The site-information field<br />
can be used by a site in any manner it chooses.)<br />
Data Type: condition<br />
b = EXCLUSIVE_ASSIGN<br />
Indicates whether or not the file must be assigned exclusively. This item is intended<br />
primarily for use with INIT_PROGRAM_FILE values other than NONE.<br />
Data Type: condition<br />
SITE_INFO<br />
Indicates the new value for the site-information field. Must be zero if<br />
CHG_SITE_INFO = FALSE.<br />
Data Type: unsigned integer<br />
4–6 7830 9796–013
4.1.3. File Identifier<br />
Changing File Attributes<br />
This file identifier parameter names the file on which the function operates. The named<br />
file must be a cataloged file if file attribute changes are specified for any of the following<br />
items:<br />
• PROJECT_ID<br />
• ACCOUNT_ID<br />
• ROLLOUT_PROHIBITED<br />
• DIRECTORY_DISABLE<br />
• WRITE_DISABLE<br />
• BACKUP_DISABLE<br />
• CACHE_DISABLE<br />
• READ_ONLY<br />
• WRITE_ONLY<br />
• CHG_SITE_INFO<br />
The named file must be an empty, sector-addressable mass storage file to which the<br />
caller has read and write access if program file initialization is specified by an<br />
INIT_PROGRAM_FILE item value other than NONE.<br />
See 2.3 for a detailed description of this parameter.<br />
4.1.4. Work Area<br />
The CHG_FILE function requires 1,000 words for its work area.<br />
4.2. Change File Cycle Attributes (CHG_FILE_CYC)<br />
The CHG_FILE_CYC function changes the F-cycle limit associated with a specified<br />
F-cycle series of files.<br />
When the cycle limit of an F-cycle series is reduced, files that exist in the F-cycle series<br />
might fall outside the new limit. The CHG_FILE_CYC function gives you the following<br />
two options for handling this situation:<br />
• Make the change and delete the extra files<br />
• Do not make the change and return an error if the change causes the deletion of any<br />
files<br />
When this function deletes extra files, it does so only if all of them can be deleted.<br />
When it must delete files, the function changes the cycle limit only if it successfully<br />
deleted the extra files.<br />
Since the information changed by this function must be the same for all files in an Fcycle<br />
series, the calling program may not specify a specific F-cycle when it calls this<br />
7830 9796–013 4–7
Changing File Attributes<br />
function. If the calling program specifies an internal file name for this function, the<br />
internal file name should not refer to a file with a specific F-cycle.<br />
4.2.1. Parameters<br />
The CHG_FILE_CYC function has the following parameters, each of which is described in<br />
the following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Work Area<br />
4.2.2. Function Packet<br />
The structure of the CHG_FILE_CYC function packet is defined in element<br />
FP$CHGFILCYC. See Figure 4–2.<br />
GENERIC PART<br />
0 a MAX_F_CYCLES<br />
1 F_CYCLES_RETAINED F_CYCLES_DELETED<br />
Item Descriptions<br />
a = ALLOW_DELETION<br />
Figure 4–2. CHG_FILE_CYC Function Packet Items<br />
If the calling program sets this item to TRUE and if this function causes the F-cycle<br />
limit to become less than the number of F-cycles that currently exist, the change is<br />
made and the oldest F-cycles are deleted so that the number retained falls within the<br />
new limit. (If all F-cycles are deleted, the entire F-cycle series is deleted.) If the<br />
calling program sets this item to FALSE and if the change causes one or more<br />
F-cycles to be deleted, the function does not change the F-cycle limit, and returns an<br />
error.<br />
Data Type: condition<br />
MAX_F_CYCLES<br />
Indicates the maximum number of files that can be in the same F-cycle series as this<br />
file.<br />
Data Type: unsigned integer range (0 – 32)<br />
4–8 7830 9796–013
F_CYCLES_RETAINED<br />
Changing File Attributes<br />
Returns the number of F-cycles that exist after the change is made. This number<br />
includes files that are cataloged, to-be-cataloged, and to-be-deleted.<br />
Data Type: unsigned integer range (0 – 32), returned<br />
F_CYCLES_DELETED<br />
Returns the number of F-cycles that this function deleted. Always 0 when<br />
ALLOW_DELETION = FALSE.<br />
Data Type: unsigned integer range (0 – 32), returned<br />
4.2.3. File Identifier<br />
The file identifier parameter names the file on which the function operates. The named<br />
file must be cataloged. Because this function operates on an entire F-cycle series of<br />
files, the calling program must set F_CYCLE_TYPE in this parameter to UNSPECIFIED. If<br />
the calling program specifies an internal file name in this parameter, the internal file<br />
name should not refer to a file with a specific F-cycle. See 2.3 for a description of this<br />
parameter.<br />
4.2.4. Work Area<br />
The amount of work area required by the CHG_FILE_CYC function is the larger of 1,000<br />
and (600 + 60*N) words, where N is the number by which the F-cycle range is reduced.<br />
The minimum amount of 1,000 words is sufficient unless the F-cycle range is reduced by<br />
more than 6. The maximum amount of 2,600 words is sufficient for the worst case.<br />
7830 9796–013 4–9
Changing File Attributes<br />
4.3. Change File Security Attributes<br />
(CHG_FILE_SEC)<br />
The CHG_FILE_SEC function changes security attributes that apply to all files of a<br />
specified F-cycle series of files.<br />
Because the information that this function changes must be the same for all files in an<br />
F-cycle series, a program may not specify a specific F-cycle when it calls this function.<br />
For systems with file ownership configured (SENTRY_CONTROL = TRUE), to change the<br />
security attributes of a file, you must own the file, the file must be unowned, or you<br />
must have security administrator privileges. In some cases, the security system restricts<br />
the security attributes you can change for a file. PCFP returns an error condition any<br />
time you attempt to change security attributes for which you have insufficient privileges.<br />
See the Security Administration for ClearPath OS 2200 Help for the requirements for<br />
changing the security attributes of a file.<br />
For systems without file ownership configured (SENTRY_CONTROL = FALSE), only the<br />
privacy state of a file can be changed.<br />
4.3.1. Parameters<br />
The CHG_FILE_SEC function has the following parameters, each of which is described in<br />
the following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Work Area<br />
4–10 7830 9796–013
4.3.2. Function Packet<br />
Changing File Attributes<br />
This structure of the function packet for CHG_FILE_SEC is defined in element<br />
FP$CHGFILSEC. See Figure 4–3.<br />
GENERIC PART<br />
0 a b CLEARANCE_LEVEL<br />
1<br />
2 FILE_OWNER_USER_ID<br />
3<br />
4 PRIVACY<br />
5 ACR_NAME<br />
6 ACR_NAME<br />
Item Descriptions<br />
a = CHG_CLEARANCE_LEVEL<br />
Figure 4–3. CHG_FILE_SEC Function Packet Items<br />
Indicates if PCFP is to change the clearance level of the file. If TRUE, PCFP obtains<br />
the new value from CLEARANCE_LEVEL.<br />
Data Type: condition<br />
b = CHG_FILE_OWNER_USER_ID<br />
Indicates if PCFP is to change the owner user-id of the file. If TRUE, PCFP obtains<br />
the new value from FILE_OWNER_USER_ID.<br />
Data Type: condition<br />
CLEARANCE_LEVEL<br />
Indicates the new clearance level of the file. Must be zero unless the calling<br />
program set CHG_CLEARANCE_LEVEL = TRUE.<br />
Data Type: unsigned integer range (0 – 63)<br />
7830 9796–013 4–11
Changing File Attributes<br />
FILE_OWNER_USER_ID<br />
Indicates the user-id of the new owner of the file. Must be null unless the calling<br />
program set CHG_FILE_OWNER_USER_ID = TRUE. If the calling program set<br />
CHG_FILE_OWNER_USER_ID = TRUE, a value of null for this item causes the file to<br />
become unowned. Note that changing the FILE_OWNER_USER_ID may cause the<br />
security system to remove the ACR for a file, which can change the privacy state of<br />
the file, even when PRIVACY = NO_CHG is specified.<br />
Data Type: characters (12)<br />
PRIVACY<br />
Indicates how this function is to change the privacy state of the file. If the calling<br />
program set PRIVACY = SEMIPRIVATE, it must specify a non-null value for<br />
ACR_NAME.<br />
Data Type: value-list<br />
NO_CHG = 0<br />
PRIVATE = 1<br />
SEMIPRIVATE = 2<br />
PUBLIC = 3<br />
ACR_NAME<br />
Indicates the name of the ACR that PCFP is to attach to the file. The ACR specified<br />
must be owned by the user-id of the run calling PCFP. The program must set this<br />
item to an actual ACR name if it also sets PRIVACY = SEMIPRIVATE, or it must set<br />
this item to null if it sets PRIVACY to any value except SEMIPRIVATE.<br />
Data Type: characters (6)<br />
4.3.3. File Identifier<br />
The file identifier parameter names the file on which the function operates. The named<br />
file must be cataloged. Because this function operates on an entire F-cycle series of<br />
files, the calling program must set F_CYCLE_TYPE in this parameter to UNSPECIFIED.<br />
See 2.3 for a description of this parameter.<br />
4.3.4. Work Area<br />
The CHG_FILE_SEC function requires a work area of 1,000 words.<br />
4–12 7830 9796–013
4.4. Change File Keys (CHG_FILE_KEYS)<br />
Changing File Attributes<br />
The CHG_FILE_KEYS function changes the read key and/or write key associated with an<br />
F-cycle series of files.<br />
Because the information that this function changes must be the same for all files in an<br />
F-cycle series, a program may not specify a specific F-cycle when it calls this function.<br />
When a program calls this function, it must specify the old keys in the file identifier<br />
parameter and the new keys in the function packet.<br />
4.4.1. Parameters<br />
The CHG_FILE_KEYS function has the following parameters, each of which is described<br />
in the following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Work Area<br />
4.4.2. Function Packet<br />
This structure of the CHG_FILE_KEYS function packet is defined in element<br />
FP$CHGFILKEY. See Figure 4–4.<br />
GENERIC PART<br />
0 NEW_READ_KEY<br />
1 NEW_READ_KEY<br />
2 NEW_WRITE_KEY<br />
3 NEW_WRITE_KEY<br />
Figure 4–4. CHG_FILE_KEYS Function Packet Items<br />
7830 9796–013 4–13
Changing File Attributes<br />
Item Descriptions<br />
NEW_READ_KEY<br />
Indicates the new read key for the file. A value of blanks indicates that PCFP is to<br />
remove the read key of the file. A value of null indicates that PCFP does not change<br />
any existing read key for the file.<br />
Data Type: characters (6)<br />
NEW_WRITE_KEY<br />
Indicates the new write key for the file. A value of blanks indicates that PCFP is to<br />
remove the write key of the file. A value of null indicates that PCFP is not to change<br />
any existing write key for the file.<br />
Data Type: characters (6)<br />
4.4.3. File Identifier<br />
The file identifier parameter names the file on which the function operates. The named<br />
file must be cataloged. Because this function operates on an entire F-cycle series of<br />
files, the calling program must set F_CYCLE_TYPE in this parameter to UNSPECIFIED.<br />
See 2.3 for a description of this parameter.<br />
If you are changing the keys of a file that already has a read key or a write key, the calling<br />
program must specify these in the file identifier. If the calling program does not specify<br />
them or if it specifies them incorrectly, the Exec will abort the calling program and print<br />
the following message:<br />
FAC KEY ERR.<br />
4.4.4. Work Area<br />
The CHG_FILE_KEYS function requires a work area of 1,000 words.<br />
4–14 7830 9796–013
4.5. Change File Name (CHG_FILE_NAME)<br />
Changing File Attributes<br />
The CHG_FILE_NAME function changes the qualifier and/or file name associated with a<br />
specified F-cycle series of files.<br />
Because the information that this function changes must be the same for all files in an<br />
F-cycle series, a program may not specify a specific F-cycle when it calls this function.<br />
When a program calls this function, the current file is named by the file identifier<br />
parameter and the new qualifier and/or file name are specified in the function packet.<br />
The Exec Administration <strong>Reference</strong> <strong>Manual</strong> contains a complete description of<br />
conditions that must be met for a successful name change and the operational<br />
considerations and restrictions that can exist because a file can be known by both an old<br />
and a new name. The most common conditions for a successful name change are<br />
summarized here:<br />
• The requester must have delete access to the file.<br />
• No file in the F-cycle series can be unloaded.<br />
• No file in the F-cycle series can be on a symbiont queue.<br />
• The new qualifier and file name cannot currently exist.<br />
After a successful name change, the following are the most common operational<br />
considerations and restrictions:<br />
• Following the name change, the file is marked as not having a current backup. It<br />
cannot be reverted until it is backed up with the new file name.<br />
• File assignments and @USE names continue to be associated with the old qualifier<br />
and old file name. To avoid operational problems we strongly recommend that you<br />
free all of the files in the F-cycle series and all associated @USE names immediately<br />
following the CHG_FILE_NAME function.<br />
• If the name change is performed on a cataloged labeled tape file that was previously<br />
written without the F file assignment option, the tape cannot be read when assigned<br />
with the new file name.<br />
4.5.1. Parameters<br />
The CHG_FILE_NAME function has the following parameters, each of which is described<br />
in the following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Work Area<br />
7830 9796–013 4–15
Changing File Attributes<br />
4.5.2. Function Packet<br />
The structure of the CHG_FILE_NAME function packet is defined in element<br />
FP$CHGFILNAM. See Figure 4–5.<br />
0 a b<br />
1<br />
GENERIC PART<br />
2 NEW_QUALIFIER<br />
3<br />
4<br />
5 NEW_FILENAME<br />
6<br />
7<br />
8 QUALIFIER_AFTER_CHG<br />
9<br />
10<br />
11 FILENAME_AFTER_CHG<br />
12<br />
Item Descriptions<br />
a = CHG_QUALIFIER<br />
Figure 4–5. CHG_FILE_NAME Function Packet Items<br />
Indicates if the qualifier of the file is to be changed. If TRUE, the qualifier will be<br />
changed as specified in NEW_QUALIFIER. If FALSE, the qualifier will not be<br />
changed and NEW_QUALIFIER must be set to a null value.<br />
Data type: condition<br />
b = CHG_FILENAME<br />
Indicates if the file name of the file is to be changed. If TRUE, the file name will be<br />
changed as specified in NEW_FILENAME. If FALSE, the file name will not be<br />
changed and NEW_FILENAME must be set to a null value.<br />
Data type: condition<br />
4–16 7830 9796–013
NEW_QUALIFIER<br />
Changing File Attributes<br />
Indicates the new qualifier for the file. A null value specifies a change to the default<br />
qualifier for the run. A value of spaces specifies a change to the implied qualifier for<br />
the run. Must be a null value if CHG_QUALIFIER is FALSE.<br />
Data type: characters (12)<br />
NEW_FILENAME<br />
Indicates the new file name for the file. Must be a null value if CHG_FILENAME is<br />
FALSE.<br />
Data type: characters (12)<br />
QUALIFIER_AFTER_CHG<br />
Indicates the new qualifier for the file, following a successful name change.<br />
Data type: characters (12), returned<br />
FILENAME_AFTER_CHG<br />
Indicates the new file name for the file, following a successful name change.<br />
Data type: characters (12), returned<br />
4.5.3. File Identifier<br />
The file identifier parameter names the file on which the function operates. The named<br />
file must be cataloged. Because this function operates on an entire F-cycle series of<br />
files, the calling program must set F_CYCLE_TYPE in this parameter to UNSPECIFIED.<br />
See 2.3 for a description of this parameter.<br />
4.5.4. Work Area<br />
The CHG_FILE_NAME function requires a work area of 1,000 words.<br />
7830 9796–013 4–17
Changing File Attributes<br />
4–18 7830 9796–013
Section 5<br />
Copying Between Files<br />
This section describes the following four functions that copy the contents of one file to<br />
another file. Because tape files require information different from mass storage files,<br />
PCFP provides four functions to handle the various combinations of tape and mass<br />
storage files.<br />
• The copy RAF to RAF function (COPY_RAF_RAF) copies the contents of one mass<br />
storage random-access file to another random-access file.<br />
• The copy RAF to SAF function (COPY_RAF_SAF) copies a mass storage<br />
random-access file to a tape sequential-access file.<br />
• The copy SAF to RAF function (COPY_SAF_RAF) copies a logical file from a tape<br />
sequential-access file to a mass storage random-access file.<br />
• The copy SAF to SAF function (COPY_SAF_SAF) copies a logical file from one tape<br />
file to another tape file.<br />
5.1. Copy RAF to RAF (COPY_RAF_RAF)<br />
The COPY_RAF_RAF function copies the contents of one mass storage random-access<br />
file to another random-access file. It handles files on sector-addressable mass storage<br />
and on word-addressable mass storage.<br />
The following options are provided with this function:<br />
• Perform the copy only if the destination file is empty (that is, if the destination file<br />
has no mass storage allocated to it). Use this option to prevent inadvertent<br />
destruction of data already in the destination file.<br />
• If the data copied from the source file is less than the original size of the destination<br />
file, PCFP can handle the excess mass storage in the destination file in one of the<br />
following ways:<br />
− Leave it allocated to the destination file<br />
− Release it, but only back to the initial reserve of the destination file<br />
− Release all of it<br />
Use this option to control the unused part of the destination file.<br />
• Zero-fill any excess mass storage that is released from the destination file. Use this<br />
option to ensure that sensitive data previously in the destination file is not released<br />
to the operating system.<br />
This function causes exclusive assignment of the destination file, but not the source file.<br />
7830 9796–013 5–1
Copying Between Files<br />
5.1.1. Parameters<br />
The COPY_RAF_RAF function has the following parameters, each of which is described<br />
in the following subsections:<br />
• Function Packet<br />
• Source File Identifier<br />
• Destination File Identifier<br />
• Work Area<br />
5.1.2. Function Packet<br />
The structure of the COPY_RAF_RAF function packet is defined in element<br />
FP$CPYRAFRAF. See Figure 5–1.<br />
GENERIC PART<br />
0 a c STORAGE_TO_RELEASE<br />
1 AMOUNT_COPIED<br />
Figure 5–1. COPY_RAF_RAF Function Packet Items<br />
Item Descriptions<br />
a = PREVENT_OVERCOPY<br />
If TRUE, PCFP ensures that the destination file is empty before it copies any data<br />
into it. The run of the calling program must have read privileges for the destination<br />
file if this item is set to TRUE.<br />
Data Type: condition<br />
c = ZERO_RELEASED_STORAGE<br />
Indicates if any excess mass storage released by PCFP during the copy operation is<br />
to be cleared to zero before it is released. This item has meaning only if the calling<br />
program sets STORAGE_TO_RELEASE to a value other than NONE.<br />
Data Type: condition<br />
5–2 7830 9796–013
STORAGE_TO_RELEASE<br />
Copying Between Files<br />
Indicates to what extent PCFP is to release any excess mass storage in the<br />
destination file.<br />
Data Type: value-list<br />
NONE = 0<br />
ALL_BUT_INITIAL_RESERVE = 1<br />
ALL_STORAGE = 2<br />
AMOUNT_COPIED<br />
Returns the number of words of file text that PCFP copied from the source file to the<br />
destination file.<br />
Data Type: unsigned integer, returned<br />
5.1.3. Source File Identifier<br />
The source file identifier parameter names the file from which data is copied. The<br />
named file must be a mass storage file for which the run of the calling program has read<br />
privileges. See 2.3 for a description of this parameter.<br />
5.1.4. Destination File Identifier<br />
The destination file identifier parameter names the file to which data is copied. The<br />
named file must be a mass storage file for which the run of the calling program has write<br />
privileges. See 2.3 for a description of this parameter.<br />
5.1.5. Work Area<br />
The size of the work area that the calling program provides for PCFP affects the<br />
performance of the COPY_RAF_RAF function. Because a large file cannot fit in main<br />
memory, this function copies a file one buffer at a time. The size of each buffer is<br />
between 1 and 16 mass storage tracks. I/O is most efficient with large buffers, so PCFP<br />
allocates the largest buffers possible within the work area that the calling program<br />
provides.<br />
If the source file is cataloged mass storage, PCFP uses the MFD device area descriptor<br />
(DAD) tables to determine the mass storage addresses to be read. For files with many<br />
DAD tables (fragmented files) this operation is much more efficient when larger DAD<br />
table buffers are used. When this is the case, PCFP can make use of additional work<br />
area for DAD table buffers.<br />
The following formula indicates the number of words of work area that PCFP can use so<br />
that buffers N tracks in size (1
Copying Between Files<br />
When the source file is a temporary file or a small or unfragmented cataloged file, a<br />
value of 800 should be used for the constant K. This value allows at least 168 words to<br />
be allocated for DAD table buffers, for all values of N.<br />
When the source file is a large or fragmented cataloged file, a value of 2,500 should be<br />
used for the constant K. This value allows at least 1,792 words to be allocated for DAD<br />
table buffers, for all values of N.<br />
The minimum work area size for this function is 4,500 words and allows PCFP to allocate<br />
buffers one track in size and to allocate at least 168 words for DAD table buffers. The<br />
maximum work area size for this function is 63,000 words and allows PCFP to allocate<br />
buffers 16 tracks in size and to allocate the maximum size DAD table buffer, 4,088<br />
words.<br />
There is little advantage to the calling program supplying this function with a work area<br />
larger than this maximum.<br />
If you expect to use the COPY_RAF_RAF function in the calling program to copy only<br />
small files (less than 50 tracks), a small work area size (1 to 4 tracks) is acceptable.<br />
However, if you expect that the files the calling program copies with this function might<br />
be large, a work area large enough for buffers 8 to 16 tracks in size is recommended.<br />
The larger the buffer size you allow, the faster the copy operation will complete. For<br />
very large files, always use the maximum work area size.<br />
5.2. Copy RAF to SAF (COPY_RAF_SAF)<br />
The COPY_RAF_SAF function copies a mass storage random-access file to a tape<br />
sequential-access file. The file is written to tape using the FURPUR (COPY,G) format.<br />
After this function executes, the tape file is positioned at its logical end, ready to copy<br />
another file. This operation always writes a hardware EOF mark at the end of the logical<br />
file.<br />
The COPY_RAF_SAF function provides the following options:<br />
• Write the logical file to the tape using either the revised or the obsolete variant of the<br />
FURPUR tape format. The revised variant allows PCFP to operate more efficiently<br />
when it later reads the tape file, but the revised variant cannot be read by versions of<br />
the FURPUR processor level 30R1 or lower.<br />
• For the revised FURPUR format, the calling program can specify the size of the<br />
physical blocks to be written, or allow PCFP to choose the size of the physical<br />
blocks. For the obsolete FURPUR format, the calling program cannot choose the<br />
size of the physical blocks.<br />
5–4 7830 9796–013
Copying Between Files<br />
• If the COPY_RAF_SAF function attempts to swap beyond the last volume of the<br />
destination file (because PCFP reaches the physical end of the last volume before all<br />
the data is copied), PCFP takes one of the following actions:<br />
− Returns with error status. (In this case, the tape is left positioned at the end of<br />
its last volume.)<br />
− Dynamically extends the tape file. (To accomplish this, PCFP solicits the<br />
operator to mount and identify the volume to be appended to the file.)<br />
• PCFP can calculate and save checksum values for each track of the logical file that it<br />
writes to the destination file. (If checksum values are not saved with the logical file,<br />
checksum checking is automatically bypassed when the logical file is subsequently<br />
read by PCFP.)<br />
• For a destination file on unlabeled tape, PCFP does one of the following:<br />
− Writes only a single EOF mark to delimit the end of the logical file. (If this<br />
alternative is chosen, the CLOSE_SAF function should be called if no further<br />
logical files are written to the tape. Failure to do so means that the logical end<br />
cannot be detected on a subsequent read of the tape.)<br />
− Writes two consecutive EOF marks following the logical file, and backspaces the<br />
tape so that it is positioned between the EOF marks. The consecutive EOF<br />
marks indicate the logical end of tape, while the backspacing means that writing<br />
a subsequent logical file to the tape will overwrite the logical end mark. (If this<br />
alternative is chosen, there is no need to call CLOSE_SAF.)<br />
Note that both alternatives apply to all types of unlabeled tape, including<br />
quarter-inch cartridge tape.<br />
• Return the block-id that corresponds to the beginning of the destination file. The<br />
block-id can be saved and used later with the MOVE_SAF function to quickly position<br />
the tape to the beginning of the file.<br />
• After completing the copy, ensure that all data has been written from the tape buffer<br />
to the physical destination tape. This is known as synchronizing the host system and<br />
the tape drive and is normally done at the end of each tape file by the Exec or by the<br />
tape subsystem. However, when the BUFTAP buffered-write mode is enabled for<br />
the destination tape, the Exec improves tape write performance by inhibiting this<br />
synchronization. Then, it is your responsibility to perform the synchronization when<br />
desired to establish checkpoints in case a tape write error is reported later. This<br />
option is provided to allow you to select when to perform the synchronization.<br />
7830 9796–013 5–5
Copying Between Files<br />
Before the COPY_RAF_SAF function is used, the current position of the destination file<br />
must be one of the following:<br />
• At the load point. In this case, this function obliterates any logical files that might<br />
have previously been copied to the tape file.<br />
• At the start of a logical file previously copied to the tape. (That is, the tape must be<br />
positioned immediately following the EOF mark that delimits the start of a logical<br />
file.) In this case, this function obliterates the logical file at which the tape is<br />
positioned, and any subsequent logical files. Logical files prior to the current position<br />
of the tape are left intact.<br />
• At the logical end of the tape. (That is, following the last logical file on the tape.) In<br />
this case, all logical files previously on the tape are left intact. Note that a tape file is<br />
always positioned at its logical end following a successful copy of a logical file to the<br />
tape.<br />
If the current position of the tape is in the middle of a logical file (that is, not immediately<br />
following an EOF mark), this function returns error code fp_err_not_after_eof, and copies<br />
nothing to the tape. To handle this situation, you can reposition the tape using the<br />
MOVE_SAF function.<br />
The COPY_RAF_SAF function returns the following information concerning the<br />
destination tape file.<br />
• Identifiers of all the volumes on which the logical file was written.<br />
• Volume-relative position of the initial (possibly only) part of the logical file.<br />
• Number of mass storage words copied.<br />
5.2.1. Parameters<br />
The COPY_RAF_SAF function has the following parameters, which are discussed next in<br />
this section.<br />
• Function Packet<br />
• Source File Identifier<br />
• Destination File Identifier<br />
• User Descriptor Data<br />
• Return Entry<br />
• Work Area<br />
5–6 7830 9796–013
5.2.2. Function Packet<br />
The structure of the COPY_RAF_SAF function packet is defined in element<br />
FP$CPYRAFSAF. See Figure 5–2.<br />
0 a b c d<br />
GENERIC PART<br />
RETURN-INFORMATION PART<br />
1 DEST_FORMAT DEST_BLOCK_SIZE<br />
Copying Between Files<br />
2 ON_END_OF_DEST_FILE<br />
3<br />
4<br />
5<br />
6<br />
7<br />
8 AMOUNT_COPIED<br />
Item Descriptions<br />
INTERFACE_LEVEL<br />
Figure 5–2. COPY_RAF_SAF Function Packet Items<br />
Contained in the GENERIC PART of the function packet and indicates the level of the<br />
packet. The calling program should set this item to the value<br />
FP_INTERFACE_LEVEL_3.<br />
• If this item is set to FP_INTERFACE_LEVEL_1, then<br />
− RETURN_BLOCK_ID must be FALSE.<br />
− SYNCHRONIZE must be FALSE.<br />
− The return entry has a format different than that described in 5.2.6.<br />
• If this item is set to FP_INTERFACE_LEVEL_2, then<br />
− SYNCHRONIZE must be FALSE.<br />
− The return entry has a format different than that described in 5.2.6.<br />
Data Type: unsigned integer<br />
7830 9796–013 5–7
Copying Between Files<br />
a = OMIT_LOG_END_MARK<br />
This item is applicable only for destination files on unlabeled tapes. It is ignored for<br />
destination files on labeled tapes. A value of FALSE indicates that PCFP is to write a<br />
logical end mark, a mark composed of two consecutive EOF marks, following the<br />
logical file on the destination tape file. In this case, PCFP repositions the tape<br />
between the EOF marks, so that a subsequent copy overwrites the second EOF<br />
mark. A value of TRUE indicates that PCFP is to write only a single EOF mark to<br />
delimit the end of the logical file. In this case, it is the responsibility of the calling<br />
program to call the CLOSE_SAF function after it has copied the last file to the tape.<br />
Data Type: condition<br />
b = SAVE_CHECKSUMS<br />
If TRUE, PCFP calculates and saves a checksum value for each track of the logical<br />
file it writes to the destination file. If this item is FALSE, PCFP does not calculate a<br />
checksum value for each track. This item must be TRUE if the calling program also<br />
sets WRITE_OBSOLETE_VARIANT to TRUE, and the logical file is to be read<br />
subsequently by the FURPUR processor (@COPY,G command).<br />
Data Type: condition<br />
c = WRITE_OBSOLETE_VARIANT<br />
If TRUE, PCFP writes the obsolete variant of the FURPUR format to the destination<br />
file, instead of the revised variant. This item can be TRUE only if the calling program<br />
set DEST_BLOCK_SIZE = 0 or 1.<br />
Data Type: condition<br />
d = RETURN_BLOCK_ID<br />
If TRUE, PCFP returns the block-id corresponding to the beginning of the destination<br />
file in the return entry (see 5.2.6). This item can be TRUE only if INTERFACE_LEVEL<br />
has a value of at least FP_INTERFACE_LEVEL_2.<br />
Data Type: condition<br />
5–8 7830 9796–013
e = SYNCHRONIZE<br />
Copying Between Files<br />
If TRUE and if the buffered-write mode BUFTAP is enabled, after writing the logical<br />
file, ensure that all buffered data has been successfully written to tape. If necessary,<br />
a synchronize (FSAFE$) I/O function is issued. Note that synchronization increases<br />
the time to write this file, as if the buffered-write mode BUFFIL was enabled. To<br />
maximize performance, this item should be set to TRUE only periodically to establish<br />
error recovery checkpoints. This item is ignored if the buffered-write mode is<br />
BUFOFF, BUFON, or BUFFIL. This item is also ignored for unlabeled tapes when<br />
OMIT_LOG_END_MARK is FALSE. In these cases, the system and the tape are<br />
implicitly synchronized by the Exec or by the tape subsystem. This item can be<br />
TRUE only if INTERFACE_LEVEL has a value of at least FP_INTERFACE_LEVEL_3.<br />
Data Type: condition<br />
DEST_FORMAT<br />
Indicates the format of the logical file that PCFP writes to the destination SAF.<br />
Data Type: value-list<br />
FURPUR = 1 (This is currently the only legal value for this item.)<br />
DEST_BLOCK_SIZE<br />
A nonzero value indicates the size of the physical blocks (in tracks) that PCFP writes<br />
to the tape file. If the value 0 is specified, PCFP chooses the block size for the<br />
destination file.<br />
Data Type: integer range (0 – 16)<br />
7830 9796–013 5–9
Copying Between Files<br />
ON_END_OF_DEST_FILE<br />
Indicates what action PCFP takes if it encounters the physical end of the last volume<br />
of the destination tape file before it completes the copy operation.<br />
Data Type: value-list<br />
RTN_ERROR = 0<br />
Indicates that PCFP does not complete the copy operation and returns an error<br />
status to the calling program.<br />
EXTEND_TO_BLANK_VOLUME = 1<br />
Indicates that PCFP extends the tape file by requesting a BLANK volume.<br />
System actions on this request depend on many factors, including but not<br />
limited to<br />
• Labeled or unlabeled tape<br />
• Specifications on the tape file @ASG<br />
• Freestanding or library tape unit<br />
• System configuration parameters<br />
• Presence of Media Manager<br />
• Site unique procedures<br />
For compatibility, the previous value name SOLICIT_OPR can also be used.<br />
AMOUNT_COPIED<br />
Returns the number of words of file text copied from the source file to the<br />
destination file.<br />
Data Type: unsigned integer, returned<br />
5.2.3. Source File Identifier<br />
The source file identifier parameter names the file from which data is copied. The<br />
named file must be a mass storage file for which the run of the calling program has read<br />
privileges. See 2.3 for a description of this parameter.<br />
5.2.4. Destination File Identifier<br />
The destination file identifier parameter names the file to which data is copied. The<br />
named file must be a tape file for which the run of the calling program has write<br />
privileges. See 2.3 for a detailed description of this parameter.<br />
5.2.5. User Descriptor Data<br />
The user descriptor data parameter is currently unused and must be null.<br />
5–10 7830 9796–013
5.2.6. Return Entry<br />
Copying Between Files<br />
The layout and item descriptions of the return entry for COPY_RAF_SAF are defined<br />
below. This function produces one return entry that gives information about the<br />
placement of the logical file on the destination SAF. This return entry is defined in<br />
element FP$RTN$SAFI. See Figure 5–3.<br />
Note: Figure 5–3 shows the new format that is returned when INTERFACE_LEVEL has<br />
a value of at least FP_INTERFACE_LEVEL_3. New return entry definitions must be used<br />
when using the new interface level.<br />
• For C users, the definition name is fp_rtn_saf_info_3_type.<br />
• For COBOL users, the definition name is FP-RTN-SAF-INFO-3.<br />
• For FORTRAN users, the definition name is FP$RTN$SAFI3.<br />
If you modify an existing COPY_RAF_SAF or COPY_SAF_SAF function to use an<br />
INTERFACE_LEVEL value of FP_INTERFACE_LEVEL_3, you must also modify the return<br />
entry definition to use the new definition name. For compatibility, the previous definition<br />
names are unchanged and describe the interface level 1 and 2 return entries. The format<br />
of the interface level 1 and 2 return entries is described in the previous definitions.<br />
7830 9796–013 5–11
Copying Between Files<br />
0 RESULT_INDICATOR<br />
1 NUM_VOLS ENTRY_SIZE<br />
2 LOGICAL_FILE_POSITION<br />
3 BLOCK_ID<br />
4 VOL_ID<br />
5 VOL_ID<br />
6 FRAGMENT_SIZE<br />
… . . .<br />
3n+1 VOL_ID<br />
3n+2 VOL_ID<br />
3n+3 FRAGMENT_SIZE<br />
Figure 5–3. COPY_RAF_SAF and COPY_SAF_SAF Return Entry Items<br />
Item Descriptions<br />
RESULT_INDICATOR<br />
Indicates whether the copy to the destination file was successful, and if not, why<br />
not. PCFP sets this item to a value other than FP_ERR_NONE (0) if the copy<br />
operation to the tape file was not completed. The returned value is an ELMS<br />
condition-id that indicates the reason the operation was not performed.<br />
Data Type: ELMS condition-id<br />
NUM_VOLS<br />
Indicates the number of volumes of the destination file that were required to contain<br />
the logical file.<br />
Data Type: unsigned integer<br />
ENTRY_SIZE<br />
Indicates the total size in words of this return entry.<br />
Data Type: unsigned integer<br />
LOGICAL_FILE_POSITION<br />
Indicates the volume-relative position of the first (possibly only) part of the logical file<br />
written to the destination tape file.<br />
Data Type: unsigned integer<br />
5–12 7830 9796–013
BLOCK_ID<br />
Copying Between Files<br />
Indicates the block-id that corresponds to the beginning of the logical file. This item<br />
can have the following values:<br />
• Zero when the function packet RETURN_BLOCK_ID item is FALSE<br />
• Negative one (-1) if fast tape access is not supported for the destination SAF<br />
• A positive integer for valid block-ids<br />
A valid block-id can be saved and used later with the MOVE_SAF function to quickly<br />
position the SAF to the beginning of this logical file.<br />
Data Type: signed integer<br />
VOL_ID array (1:n)<br />
Indicates the identifier of the volume of the destination file containing the nth part of<br />
the logical file. The number of entries in this array equals NUM_VOLS.<br />
Data Type: characters (6)<br />
FRAGMENT_SIZE array (1:n)<br />
5.2.7. Work Area<br />
Indicates the amount of file text (in words) written to the volume of the destination<br />
file that contains the nth fragment of the logical file. The number of entries in this<br />
array equals NUM_VOLS.<br />
Data Type: unsigned integer<br />
The size of the work area that the calling program provides for PCFP affects the<br />
performance of the COPY_RAF_SAF function. Because a large file cannot fit in main<br />
memory, this function copies a file one buffer at a time. The size of each buffer is<br />
between 1 and 16 mass storage tracks. I/O is most efficient with large buffers, so PCFP<br />
allocates the largest buffers possible within the work area that the calling program<br />
provides.<br />
If the source file is cataloged mass storage, PCFP uses the MFD (DAD) tables to<br />
determine the mass storage addresses to be read. For files with many DAD tables<br />
(fragmented files) this operation is much more efficient when larger DAD table buffers<br />
are used. When this is the case, PCFP can make use of additional work area for DAD<br />
table buffers.<br />
The following formula indicates the number of words of work area that PCFP can use so<br />
that buffers N tracks in size (1
Copying Between Files<br />
When the source file is a temporary file or a small or unfragmented cataloged file, a<br />
value of 800 should be used for the constant K. This value allows at least 168 words to<br />
be allocated for DAD table buffers, for all values of N.<br />
When the source file is a large or fragmented cataloged file, a value of 2500 should be<br />
used for the constant K. This value allows at least 1,792 words to be allocated for DAD<br />
table buffers, for all values of N.<br />
The minimum work area size for this function is 4,500 words and allows PCFP to allocate<br />
buffers one track in size and to allocate at least 168 words for DAD table buffers. The<br />
maximum work area size for this function is 63,000 words and allows PCFP to allocate<br />
buffers 16 tracks in size and to allocate the maximum size DAD table buffer, 4,088<br />
words.<br />
There is little advantage to the calling program supplying this function with a work area<br />
larger than this maximum.<br />
If you expect to use this function in the calling program to copy only small files (less than<br />
50 tracks), a small work area size (1 to 4 tracks) is acceptable. However, if you expect<br />
that the files the calling program copies with this function might be large, a work area<br />
large enough for buffers 8 to 16 tracks in size is recommended. The larger the buffer<br />
size you allow, the faster the copy operation will complete. For very large files, always<br />
use the maximum work area size.<br />
In addition to performance considerations, the work area must be large enough to allow<br />
buffers at least as large as the size of the physical blocks written to the tape. The work<br />
area is used most effectively if the buffer size is a multiple of the physical block size. For<br />
example, if the physical block is 4 tracks, the size of the work area must be at least<br />
15,600 words when K is 800 (800 + 3,700*4) or 17,300 words when K is 2,500 (2,500 +<br />
3,700*4). A work area allowing buffers 4, 8, 12, and 16 tracks in size would be most<br />
effective for this example. When K is 800 the work area size would be respectively<br />
15,600, 30,400, 45,200, and 60,000 words. When K is 2,500 the work area size would<br />
be respectively 17,300, 32,100, 46,900, and 61,700 words.<br />
5.3. Copy SAF to RAF (COPY_SAF_RAF)<br />
The COPY_SAF_RAF function copies a logical file from a tape sequential-access file to a<br />
mass storage random-access file. The tape file must be positioned at the logical file to<br />
be copied before this function is called. The logical file being copied from the tape must<br />
be in the revised or obsolete variant of the FURPUR (COPY,G) format.<br />
After this function has completed successfully, the tape file is positioned at the next<br />
logical file on the tape.<br />
The COPY_SAF_RAF function has the following options:<br />
• Return to the calling program a description of the logical file that was copied.<br />
• Perform the copy only if the destination file is initially empty (that is, has no mass<br />
storage allocated to it). Use this option to prevent inadvertent destruction of the<br />
data already in the destination file.<br />
5–14 7830 9796–013
Copying Between Files<br />
• If the data copied from the source file is less than the original size of the destination<br />
file, PCFP can handle the excess mass storage in the destination file in one of the<br />
following ways:<br />
− Leaves it allocated to the destination file<br />
− Releases it, but only back to the initial reserve of the destination file<br />
− Releases all of it<br />
Use this option to control the unused part of the destination file.<br />
• Zero-fill any excess mass storage that is released from the destination file. Use this<br />
option to ensure that sensitive data previously in the destination file is not released<br />
to the operating system.<br />
• If this function attempts to swap beyond the last volume of the source tape file<br />
(because the physical end of the last volume is reached before the end of the logical<br />
file), PCFP takes one of the following actions:<br />
− Returns with error status. (In this case, the tape file is left positioned at the end<br />
of the last volume.)<br />
− Dynamically extends the tape file. (To accomplish this, PCFP solicits the<br />
operator to mount and identify the volume to be appended to the file.)<br />
• If a checksum error is detected while reading the source file, PCFP either proceeds<br />
with the copy or returns in error. If you choose the first alternative, PCFP returns the<br />
total number of checksum errors that it detects. In either case, PCFP returns the<br />
number of the track causing the first checksum error.<br />
• If a track sequence error is detected on the source file, PCFP either proceeds with<br />
the copy or returns in error. If you choose the first alternative, PCFP returns the total<br />
number of track sequence errors that it detects. In either case, PCFP returns the<br />
number of the track causing the first track sequence error.<br />
• Return the block-id that corresponds to the beginning of the source file. The block-id<br />
can be saved and used later with the MOVE_SAF function to quickly position the<br />
tape to the beginning of the file.<br />
Before the COPY_SAF_RAF function is used, the current position of the source file can<br />
be anywhere within the logical file to be copied. If necessary, this function repositions<br />
the tape to the start of the logical file before copying data from the tape. There are two<br />
exceptions for which this function cannot reposition to the start of the logical file:<br />
• The logical file is split across volumes, and the start of the logical file is on a previous<br />
volume. PCFP cannot swap volumes in the backward direction.<br />
• The tape file is on quarter-inch cartridge (QIC24). Such a tape cannot be moved<br />
backward.<br />
For either of these cases, the COPY_SAF_RAF function returns an appropriate error code<br />
and does not copy any data.<br />
7830 9796–013 5–15
Copying Between Files<br />
5.3.1. Parameters<br />
The COPY_SAF_RAF function has the following parameters, each of which is described<br />
in the following subsections:<br />
• Function Packet<br />
• Source File Identifier<br />
• Destination File Identifier<br />
• Descriptor Return Area<br />
• Work Area<br />
5.3.2. Function Packet<br />
This structure of the COPY_SAF_RAF function packet is defined in element<br />
FP$CPYSAFRAF. See Figure 5–4.<br />
GENERIC PART<br />
0 a c d f g STORAGE_TO_RELEASE<br />
1 ON_END_OF_SOURCE_FILE NUM_DEST_FILES<br />
2<br />
3 DESC_RTN_AREA_SIZE<br />
4<br />
5<br />
6<br />
7 AMOUNT_COPIED<br />
8 NUM_CHECKSUM_ERRORS<br />
9 NUM_TRACK_SEQ_ERRORS<br />
10 LOC_FIRST_CHECKSUM_ERROR<br />
11 LOC_FIRST_TRACK_SEQ_ERROR<br />
12<br />
Figure 5–4. COPY_SAF_RAF Function Packet Items<br />
5–16 7830 9796–013
Item Descriptions<br />
INTERFACE_LEVEL<br />
Copying Between Files<br />
Contained in the GENERIC PART of the function packet and indicates the level of the<br />
packet. The calling program should set this item to the value<br />
FP_INTERFACE_LEVEL_2. If this item is set to FP_INTERFACE_LEVEL_1, the item<br />
RETURN_BLOCK_ID must be FALSE and the descriptor return area has a format<br />
different than that described in 5.3.5.<br />
Data Type: unsigned integer<br />
a = PREVENT_OVERCOPY<br />
If TRUE, PCFP ensures that the destination file is empty before it copies any data<br />
into it. The run of the calling program must have read privileges for the destination<br />
file if this item is set to TRUE.<br />
Data Type: condition<br />
c = PROCESS_CHECKSUM_ERRORS<br />
Indicates whether processing continues if PCFP detects a checksum error during the<br />
copy operation.<br />
Data Type: condition<br />
d = PROCESS_TRACK_SEQ_ERRORS<br />
Indicates whether processing continues if PCFP detects a track sequence error<br />
during the copy operation.<br />
Data Type: condition<br />
f = ZERO_RELEASED_STORAGE<br />
Indicates whether PCFP clears any excess mass storage released during the copy<br />
operation. This item has meaning only if the calling program set<br />
STORAGE_TO_RELEASE to a value other than NONE.<br />
Data Type: condition<br />
g = RETURN_BLOCK_ID<br />
If TRUE, PCFP returns in the descriptor return area (see 5.3.5) the block-id that<br />
corresponds to the beginning of the source file. This item can be TRUE only if<br />
INTERFACE_LEVEL has a value of at least FP_INTERFACE_LEVEL_2.<br />
Data Type: condition<br />
7830 9796–013 5–17
Copying Between Files<br />
STORAGE_TO_RELEASE<br />
Indicates to what extent PCFP releases excess mass storage from the destination<br />
file.<br />
Data Type: value-list<br />
NONE = 0<br />
ALL_BUT_INITIAL_RESERVE = 1<br />
ALL_STORAGE = 2<br />
ON_END_OF_SOURCE_FILE<br />
Indicates what action to take if PCFP encounters the physical end of the last volume<br />
of the tape file before the end of the logical file.<br />
Data Type: value-list<br />
RTN_ERROR = 0<br />
Indicates that PCFP positions the tape file at the physical end of the last volume,<br />
and returns an error status to the calling program.<br />
EXTEND_TO_BLANK_VOLUME = 1<br />
Indicates that PCFP extends the tape file by requesting a BLANK volume.<br />
System actions on this request depend on many factors, including but not<br />
limited to the following:<br />
• Labeled or unlabeled tape<br />
• Specifications on the tape file @ASG<br />
• Freestanding or library tape unit<br />
• System configuration parameters<br />
• Presence of Media Manager<br />
• Site unique procedures<br />
For compatibility, the previous value name SOLICIT_OPR can also be used.<br />
NUM_DEST_FILES<br />
The calling program must always set this item to 1.<br />
Data Type: unsigned integer<br />
5–18 7830 9796–013
DESC_RTN_AREA_SIZE<br />
Copying Between Files<br />
Indicates the size of the parameter Descriptor Return Area into which PCFP is to<br />
place the description of the logical file read from the tape file. If this item is zero,<br />
PCFP ignores the parameter Descriptor Return Area and does not return the<br />
description of the logical file to the calling program. To have PCFP return the entire<br />
description of the logical file, the calling program must set this item to 14.<br />
Data Type: unsigned integer<br />
AMOUNT_COPIED<br />
Indicates the number of words of file text PCFP copied from the source file to the<br />
destination file.<br />
Data Type: unsigned integer, returned<br />
NUM_CHECKSUM_ERRORS<br />
Indicates the total number of checksum errors PCFP detected while reading the tape<br />
file. This item can have a value greater than 1 only if the calling program set<br />
PROCESS_CHECKSUM_ERRORS = TRUE.<br />
Data Type: unsigned integer, returned<br />
NUM_TRACK_SEQ_ERRORS<br />
Indicates the total number of track sequence errors PCFP detected while reading the<br />
tape file. This item can have a value greater than 1 only if the calling program set<br />
PROCESS_TRACK_SEQ_ERRORS = TRUE.<br />
Data Type: unsigned integer, returned<br />
LOC_FIRST_CHECKSUM_ERROR<br />
Indicates the number of the track in which PCFP detected the first checksum error<br />
while reading the logical file from tape. This value is nonzero only if<br />
NUM_CHECKSUM_ERRORS > 0.<br />
Data Type: unsigned integer, returned<br />
LOC_FIRST_TRACK_SEQ_ERROR<br />
Indicates the number of the track in which PCFP detected the first track sequence<br />
error while reading the logical file from tape. This value is nonzero only if<br />
NUM_TRACK_SEQ_ERRORS > 0.<br />
Data Type: unsigned integer, returned<br />
7830 9796–013 5–19
Copying Between Files<br />
5.3.3. Source File Identifier<br />
The source file identifier parameter names the file from which data is copied. The<br />
named file must be a tape file for which the run of the calling program has read<br />
privileges. See 2.3 for a full description of this parameter.<br />
5.3.4. Destination File Identifier<br />
This destination file identifier parameter names the file to which data is copied. The<br />
named file must be a mass storage file for which the run of the calling program has write<br />
privileges. See 2.3 for a description of this parameter.<br />
5.3.5. Descriptor Return Area<br />
With this parameter, PCFP returns the description of the logical file read from the tape<br />
file. The size of this parameter is given by the item DESC_RTN_AREA_SIZE in the<br />
function packet. Whenever DESC_RTN_AREA_SIZE = 0, PCFP ignores this parameter<br />
and does not return the description of the logical file to the calling program. To return<br />
the entire logical file description, the calling program must provide an area that is at least<br />
15 words long. The descriptor return area is defined in element FP$RTN$SAFD.<br />
Note: Figure 5–5 shows the new format that is returned when INTERFACE_LEVEL has<br />
a value of at least FP_INTERFACE_LEVEL_2. New definitions must be used when using<br />
the new interface level.<br />
• For C users, the new definition name is fp_rtn_saf_desc_2_type.<br />
• For COBOL users, the new definition name is FP-RTN-SAF-DESC-2.<br />
• For FORTRAN users, the new definition name is FP$RTN$SAFD2.<br />
If you modify an existing COPY_SAF_RAF or COPY_SAF_SAF function to use an<br />
INTERFACE_LEVEL value of FP_INTERFACE_LEVEL_2, you must also modify the<br />
descriptor return area definition to use the new definition name. For compatibility, the<br />
current definition names are unchanged and describe the interface level1 descriptor<br />
return area. The format of the interface level1 descriptor return area is described in<br />
comments contained in the current definitions.<br />
5–20 7830 9796–013
0 FORMAT BLOCK_SIZE<br />
1 VOL_ID<br />
2 VOL_ID a<br />
3 LOGICAL_FILE_POSITION<br />
4 BLOCK_ID<br />
5 DATE_TIME_COPIED<br />
6<br />
7<br />
8 QUALIFIER<br />
9<br />
10<br />
11 FILENAME<br />
12<br />
13 F_CYCLE_TYPE F_CYCLE<br />
14 HIGHEST_WORD_WRITTEN<br />
Copying Between Files<br />
Figure 5–5. Descriptor Return Area for COPY_SAF_RAF and<br />
COPY_SAF_SAF<br />
Item Descriptions<br />
FORMAT<br />
Indicates the format of the logical file PCFP reads from the tape.<br />
Data Type: value-list<br />
FURPUR = 1<br />
BLOCK_SIZE<br />
VOL_ID<br />
This is the only possible value for this item at this time.<br />
Indicates the size of the physical blocks (in tracks) in the logical file.<br />
Data Type: integer range (1 – 16)<br />
Indicates the identifier of the tape volume. (If the logical file is split across volumes,<br />
this information pertains to the initial part of the logical file.)<br />
Data Type: characters (6)<br />
7830 9796–013 5–21
Copying Between Files<br />
a = LOCATE_BLOCK<br />
Indicates if the tape has been positioned using the Locate Block (LBLK$) I/O function<br />
issued either by the PCFP MOVE_SAF function or by a caller application. If TRUE,<br />
the LOGICAL_FILE_POSITION is unknown and is set to zero.<br />
Data Type: condition<br />
LOGICAL_FILE_POSITION<br />
Indicates the volume-relative position of the logical file. (If the logical file is split<br />
across volumes, this information pertains to the initial part of the logical file.)<br />
Data Type: unsigned integer<br />
BLOCK_ID<br />
Indicates the block-id that corresponds to the beginning of the logical file. This item<br />
can have the following values:<br />
• Zero when the function packet RETURN_BLOCK_ID item is FALSE<br />
• Negative one (-1) if fast tape access is not supported for the source SAF<br />
• Negative two (-2) if this is a labeled tape that is positioned to its logical end<br />
• A positive integer for valid block-ids<br />
A valid block-id can be saved and used later with the MOVE_SAF function to quickly<br />
position the SAF to the beginning of this logical file.<br />
Data Type: signed integer<br />
DATE_TIME_COPIED<br />
Indicates the date and time the logical file was copied to the tape.<br />
Data Type: date-time<br />
QUALIFIER<br />
Indicates the qualifier of the mass storage file from which the logical file was copied.<br />
Data Type: characters (12)<br />
FILENAME<br />
Indicates the file name of the mass storage file from which the logical file was<br />
copied.<br />
Data Type: characters (12)<br />
5–22 7830 9796–013
F_CYCLE_TYPE<br />
Copying Between Files<br />
Indicates whether F_CYCLE contains an absolute F-cycle value or a relative F-cycle<br />
value. This item usually has the value ABS. However, if the logical file was copied<br />
from a temporary mass storage file assigned with a relative F-cycle, this item has the<br />
value REL.<br />
Data Type: value-list<br />
UNSPECIFIED = 0<br />
Indicates the F-cycle was not saved when the file was copied to tape.<br />
ABS = 1<br />
REL = 2<br />
F_CYCLE<br />
Indicates the F-cycle of the mass storage file from which the logical file was copied.<br />
Data Type: signed integer range (-31 through 999)<br />
Possible values are as follows:<br />
If F_CYCLE_TYPE = ABS, the F_CYCLE range is 1 to 999.<br />
If F_CYCLE_TYPE = REL, the F_CYCLE range is -31 to 1.<br />
HIGHEST_WORD_WRITTEN<br />
5.3.6. Work Area<br />
Indicates the location of the highest word of mass storage written in the logical file.<br />
Data Type: unsigned integer<br />
The size of the work area that the calling program provides for PCFP affects the<br />
performance of the COPY_SAF_RAF function. Because a large file cannot fit in main<br />
memory, this function copies a file one buffer at a time. The size of each buffer is<br />
between 1 and 16 mass storage tracks. I/O is most efficient with large buffers, so PCFP<br />
allocates the largest buffers possible within the work area that the calling program<br />
provides.<br />
The following formula indicates the number of words of work area that PCFP requires so<br />
that buffers N tracks in size (1 ≤ N ≤ 16) are allocated:<br />
Work Area Size = 800 + (3700 * N)<br />
7830 9796–013 5–23
Copying Between Files<br />
The minimum work area size for this function (4,500 words) allows PCFP to allocate<br />
buffers one track in size. The maximum work area size for this function (60,000 words)<br />
allows PCFP to allocate buffers 16 tracks in size. There is no advantage to the calling<br />
program supplying this function with a work area larger than this maximum.<br />
If you expect to use the COPY_SAF_RAF function in the calling program to copy only<br />
small files (less than 50 tracks), a small work area size (1 to 4 tracks) is acceptable.<br />
However, if you expect that the files the calling program copies with this function might<br />
be large, a work area large enough for buffers 8 to 16 tracks in size is recommended.<br />
The larger the buffer size you allow, the faster the copy operation will complete. For<br />
very large files, always use the maximum work area size.<br />
In addition to performance considerations, the work area must be large enough to allow<br />
buffers at least as large as the size of the physical blocks read from the tape. The work<br />
area is used most effectively if the buffer size is a multiple of the physical block size. For<br />
example, if the physical block is 4 tracks, the size of the work area must be at least<br />
15,600 words (800 + 3700*4). A work area with a size of 15,600, 30,400, 45,200, or<br />
60,000 words is most effective.<br />
5.4. Copy SAF to SAF (COPY_SAF_SAF)<br />
The COPY_SAF_SAF function copies a logical file from one tape file to another tape file.<br />
The logical file copied must have been written using the FURPUR (COPY,G) format.<br />
Following execution of this function, the destination tape file is positioned at its logical<br />
end, ready to accept copying out of another file. This operation always includes writing<br />
of a hardware EOF mark at the end of the logical file.<br />
This function has the following options:<br />
• Return to the calling program a description of the logical file that PCFP copied.<br />
• Write the logical file to the destination file using either the revised or the obsolete<br />
variant of the FURPUR tape format. The revised variant allows PCFP to operate<br />
more efficiently when it later reads the tape file, but the revised variant cannot be<br />
read by versions of the FURPUR processor level 30R1 or lower.<br />
• For the revised FURPUR format, the calling program can specify the size of the<br />
physical blocks to be written, or allow PCFP to choose the size of the physical<br />
blocks. For the obsolete FURPUR format, the calling program cannot choose the<br />
size of the physical blocks.<br />
• If this function attempts to swap beyond the last volume of the source file (because<br />
PCFP reaches the physical end of the last volume before the end of the logical file),<br />
or the last volume of the destination file (because PCFP reaches the physical end of<br />
the last volume before all the data is copied), PCFP takes one of the following<br />
actions:<br />
− Returns with error status. (In this case, the tape file remains positioned at the<br />
physical end of the last volume.)<br />
− Dynamically extends the tape file. (To accomplish this, PCFP solicits the<br />
operator to mount and identify the volume to be appended to the file.)<br />
5–24 7830 9796–013
Copying Between Files<br />
• If a checksum error is detected while reading the source file, PCFP either proceeds<br />
with the copy or returns in error. If you choose the first alternative, PCFP returns the<br />
total number of checksum errors that it detects. In either case, PCFP returns the<br />
number of the track causing the first checksum error.<br />
• If a track sequence error is detected on the source file, PCFP either proceeds with<br />
the copy or returns in error. If you choose the first alternative, PCFP returns the total<br />
number of track sequence errors that it detects. In either case, PCFP returns the<br />
number of the track causing the first track sequence error.<br />
• PCFP can calculate and save the checksum values for each track of the logical file<br />
that it writes to the destination file. (If checksum values are not saved with the<br />
logical file, checksum checking is automatically bypassed when the logical file is<br />
subsequently read.)<br />
• For a destination file on an unlabeled tape, PCFP does one of the following:<br />
− Writes only a single EOF mark to delimit the end of the logical file. (If this<br />
alternative is chosen, the CLOSE_SAF function should be called if no further<br />
logical files are written to the tape. Failure to do so means that the logical end<br />
cannot be detected on a subsequent read of the tape.)<br />
− Writes two consecutive EOF marks following the logical file, and backspaces the<br />
tape so that it is positioned between the EOF marks. The consecutive EOF<br />
marks indicate the logical end of tape, while the backspacing means that writing<br />
a subsequent logical file to the tape will overwrite the logical end mark. (If you<br />
choose this alternative, you do not need to call CLOSE_SAF.)<br />
This option has no effect if the destination file is on a labeled tape. Note that<br />
both alternatives apply to all types of unlabeled tape, including the quarter-inch<br />
cartridge tape.<br />
• Return the block-id that corresponds to the beginning of the source file and the<br />
block-id that corresponds to the beginning of the destination file. The block-ids can<br />
be saved and used later with the MOVE_SAF function to quickly position the tape to<br />
the beginning of either file.<br />
• After completing the copy, ensure that all data has been written from the tape buffer<br />
to the physical destination tape. This is known as synchronizing the host system and<br />
the tape drive and is normally done at the end of each tape file by the Exec or by the<br />
tape subsystem. However, when the BUFTAP buffered-write mode is enabled for<br />
the destination tape, the Exec improves tape write performance by inhibiting this<br />
synchronization. Then, it is your responsibility to perform the synchronization when<br />
desired to establish checkpoints in case a tape write error is reported later. This<br />
option is provided to allow you to select when to perform the synchronization.<br />
Before the COPY_SAF_SAF function is used, the current position of the source file can<br />
be anywhere within the logical file to be copied. If necessary, this function repositions<br />
the tape to the start of the logical file before copying data from the tape. There are two<br />
exceptions for which this function cannot reposition to the start of the logical file:<br />
• The logical file is split across volumes, and the start of the logical file is on a previous<br />
volume. PCFP cannot swap volumes in the backward direction.<br />
• The tape file is on quarter-inch cartridge (QIC24). Such a tape cannot be moved<br />
backward except to load point on the tape.<br />
7830 9796–013 5–25
Copying Between Files<br />
For either of these cases, the COPY_SAF_SAF function returns an appropriate error code<br />
and does not copy any data.<br />
Before this function is used, the current position of the destination file must be one of<br />
the following:<br />
• At the load point. In this case, this function obliterates any logical files that might<br />
have previously been copied to the tape file.<br />
• At the start of a logical file previously copied to the tape. (That is, the tape must be<br />
positioned immediately following the EOF mark that delimits the start of a logical<br />
file.) In this case, this function obliterates the logical file at which the tape is<br />
positioned, and any subsequent logical files. Logical files prior to the current position<br />
of the tape are left intact.<br />
• At the logical end of the tape. (That is, following the last logical file on the tape.) In<br />
this case, all logical files previously on the tape are left intact. Note that a tape file is<br />
always positioned at its logical end following a successful copy of a logical file to the<br />
tape.<br />
If the current position of the destination tape is in the middle of a logical file (that is, not<br />
immediately following an EOF mark), this function returns error code<br />
fp_err_not_after_eof, and copies nothing to the tape. To handle this situation, you can<br />
reposition the tape using the MOVE_SAF function.<br />
The COPY_SAF_SAF function returns the following information about the destination file:<br />
• Identifiers of all the volumes on which the logical file was written<br />
• Volume-relative position of the initial (possibly only) part of the logical file<br />
• Number of words of file text copied<br />
Optionally, this function can also return a descriptor of the logical file that was copied<br />
from the source tape file. The description returned is the same as that returned by<br />
COPY_SAF_RAF.<br />
5.4.1. Parameters<br />
The COPY_SAF_SAF function has the following parameters, which are discussed next in<br />
this section:<br />
• Function Packet<br />
• Source File Identifier<br />
• Destination File Identifier<br />
• User Descriptor Data<br />
• Return Entry<br />
• Descriptor Return Area<br />
• Work Area<br />
5–26 7830 9796–013
5.4.2. Function Packet<br />
The structure of the COPY_SAF_SAF function packet is defined in element<br />
FP$CPYSAFSAF. See Figure 5–6.<br />
0 b c e g h i<br />
1 NUM_DEST_FILES<br />
GENERIC PART<br />
RETURN-INFORMATION PART<br />
Copying Between Files<br />
2 DESC_RTN_AREA_SIZE<br />
3<br />
4 DEST_BLOCK_SIZE<br />
5 ON_END_OF_SOURCE_FILE ON_END_OF_DEST_FILE<br />
6<br />
7<br />
8<br />
9<br />
10<br />
11 AMOUNT_COPIED<br />
12 NUM_CHECKSUM_ERRORS<br />
13 NUM_TRACK_SEQ_ERRORS<br />
14 LOC_FIRST_CHECKSUM_ERROR<br />
15 LOC_FIRST_TRACK_SEQ_ERROR<br />
16<br />
Figure 5–6. COPY_SAF_SAF Function Packet and Return Area Items<br />
7830 9796–013 5–27
Copying Between Files<br />
Item Descriptions<br />
INTERFACE_LEVEL<br />
Contained in the GENERIC PART of the function packet and indicates the level of the<br />
packet. The calling program should set this item to the value<br />
FP_INTERFACE_LEVEL_3.<br />
• If this item is set to FP_INTERFACE_LEVEL_1, then<br />
− RETURN_BLOCK_ID must be FALSE.<br />
− SYNCHRONIZE must be FALSE.<br />
− The descriptor return entry has a format different than that described in<br />
5.3.5.<br />
− The return entry has a format different than that described in 5.2.6.<br />
• If this item is set to FP_INTERFACE_LEVEL_2, then<br />
− SYNCHRONIZE must be FALSE.<br />
− The return entry has a format different than that described in 5.2.6.<br />
Data Type: unsigned integer<br />
b = PROCESS_CHECKSUM_ERRORS<br />
Indicates whether PCFP continues processing if it detects a checksum error during<br />
the copy operation.<br />
Data Type: condition<br />
c = PROCESS_TRACK_SEQ_ERRORS<br />
Indicates whether PCFP continues processing if it detects a track sequence error<br />
during the copy operation.<br />
Data Type: condition<br />
e = OMIT_LOG_END_MARK<br />
This item is applicable only for destination files on unlabeled tapes. It is ignored for<br />
destination files on labeled tapes. A value of FALSE indicates that PCFP is to write a<br />
logical end mark, a mark composed of two consecutive EOF marks, following the<br />
logical file it writes on the destination SAF. In this case, PCFP repositions the tape<br />
between the EOF marks, so that a subsequent copy overwrites the second EOF<br />
mark. A value of TRUE indicates that PCFP is to write only a single EOF mark to<br />
delimit the end of the logical file. In this case, it is the responsibility of the calling<br />
program to call the CLOSE_SAF function after copying the last file to the tape.<br />
Data Type: condition<br />
5–28 7830 9796–013
g = SAVE_CHECKSUMS<br />
Copying Between Files<br />
If TRUE, PCFP calculates and saves a checksum value for each track of the logical<br />
file written to the destination file. If this item is FALSE, PCFP does not calculate a<br />
checksum value for each track. The calling program must set this item to TRUE if it<br />
also sets WRITE_OBSOLETE_VARIANT to TRUE, and the logical file is to be read<br />
subsequently by the FURPUR processor.<br />
Data Type: condition<br />
h = WRITE_OBSOLETE_VARIANT<br />
If TRUE, this indicates that PCFP is to write the obsolete variant of the FURPUR<br />
format to the destination file, instead of the revised variant. This item can be TRUE<br />
only if the calling program sets DEST_BLOCK_SIZE = 0 or 1.<br />
Data Type: condition<br />
i = RETURN_BLOCK_ID<br />
If TRUE, PCFP returns, in the descriptor return area (see 5.3.5), the block-id<br />
corresponding to the beginning of the source file, and in the return entry (see 5.2.6),<br />
the block-id corresponding to the beginning of the destination file. This item can be<br />
TRUE only if INTERFACE_LEVEL has a value of at least FP_INTERFACE_LEVEL_2.<br />
Data Type: condition<br />
j = SYNCHRONIZE<br />
If TRUE and if the buffered-write mode BUFTAP is enabled, after writing the logical<br />
file, ensure that all buffered data has been successfully written to tape. If necessary,<br />
a synchronize (FSAFE$) I/O function is issued. Note that synchronization increases<br />
the time to write this file, as if the buffered-write mode BUFFIL was enabled. To<br />
maximize performance, this item should be set to TRUE only periodically to establish<br />
error recovery checkpoints. This item is ignored if the buffered-write mode is<br />
BUFOFF, BUFON, or BUFFIL. This item is also ignored for unlabeled tapes when<br />
OMIT_LOG_END_MARK is FALSE. In these cases, the system and the tape are<br />
implicitly synchronized by the Exec or by the tape subsystem. This item can be<br />
TRUE only if INTERFACE_LEVEL has a value of at least FP_INTERFACE_LEVEL_3.<br />
Data Type: condition<br />
NUM_DEST_FILES<br />
The calling program must always set this item to 1.<br />
Data Type: unsigned integer<br />
7830 9796–013 5–29
Copying Between Files<br />
DESC_RTN_AREA_SIZE<br />
Indicates the size of the parameter Descriptor Return Area into which PCFP is to<br />
place the description of the logical file it reads from the source file. If this item is<br />
zero, PCFP ignores the parameter Descriptor Return Area and does not return the<br />
descriptor of the logical file to the calling program.<br />
Data Type: unsigned integer<br />
DEST_BLOCK_SIZE<br />
A nonzero value indicates the size of the physical blocks (in tracks) that PCFP writes<br />
to the destination SAF. If the calling program sets this item to zero, PCFP chooses<br />
the block size for the destination file.<br />
Data Type: integer range (0 – 16)<br />
ON_END_OF_SOURCE_FILE<br />
Indicates the action PCFP takes if it encounters the physical end of the last volume<br />
of the source tape file before the end of the logical file.<br />
Data Type: value-list<br />
RTN_ERROR = 0<br />
Indicates that PCFP positions the file at the physical end of the last volume and<br />
returns an error status to the calling program.<br />
EXTEND_TO_BLANK_VOLUME = 1<br />
Indicates that PCFP extends the tape file by requesting a BLANK volume.<br />
System actions on this request depend on many factors, including but not<br />
limited to the following:<br />
• Labeled or unlabeled tape<br />
• Specifications on the tape file @ASG<br />
• Freestanding or library tape unit<br />
• System configuration parameters<br />
• Presence of Media Manager<br />
• Site unique procedures<br />
For compatibility, the previous value name SOLICIT_OPR can also be used.<br />
5–30 7830 9796–013
ON_END_OF_DEST_FILE<br />
Copying Between Files<br />
Indicates the action PCFP takes if it encounters the physical end of the last volume<br />
of the destination tape file before completing the copy operation.<br />
Data Type: value-list<br />
RTN_ERROR = 0<br />
Indicates that PCFP does not complete the copy operation and returns an error<br />
status to the calling program.<br />
EXTEND_TO_BLANK_VOLUME = 1<br />
Indicates that PCFP extends the tape file by requesting a BLANK volume.<br />
System actions on this request depend on many factors, including but not<br />
limited to the following:<br />
• Labeled or unlabeled tape<br />
• Specifications on the tape file @ASG<br />
• Freestanding or library tape unit<br />
• System configuration parameters<br />
• Presence of Media Manager<br />
• Site unique procedures<br />
For compatibility, the previous value name SOLICIT_OPR can also be used.<br />
All of the following items contain values returned by PCFP:<br />
AMOUNT_COPIED<br />
Returns the number of words of file text copied from the source file to the<br />
destination file.<br />
Data Type: unsigned integer, returned<br />
NUM_CHECKSUM_ERRORS<br />
Returns the total number of checksum errors PCFP detected while reading the<br />
source file tape. This item can have a value greater than 1 only if the calling program<br />
set PROCESS_CHECKSUM_ERRORS = TRUE.<br />
Data Type: unsigned integer, returned<br />
7830 9796–013 5–31
Copying Between Files<br />
NUM_TRACK_SEQ_ERRORS<br />
Indicates the total number of track sequence errors PCFP detected while reading the<br />
source tape file. This item can have a value greater than 1 only if the calling program<br />
set PROCESS_TRACK_SEQ_ERRORS = TRUE.<br />
Data Type: unsigned integer, returned<br />
LOC_FIRST_CHECKSUM_ERROR<br />
Indicates the number of the track in which PCFP detected the first checksum error<br />
while reading the source tape file. This value is nonzero only if<br />
NUM_CHECKSUM_ERRORS is greater than 0.<br />
Data Type: unsigned integer, returned<br />
LOC_FIRST_TRACK_SEQ_ERROR<br />
Indicates the number of the track for which PCFP detected the first track sequence<br />
error while reading the source tape file. This value is nonzero only if<br />
NUM_TRACK_SEQ_ERRORS is greater than 0.<br />
Data Type: unsigned integer, returned<br />
5.4.3. Source File Identifier<br />
The source file identifier parameter names the file from which data is copied. The<br />
named file must be a tape file for which the run of the calling program has read<br />
privileges. See 2.3 for a full description of this parameter.<br />
5.4.4. Destination File Identifier<br />
The destination file identifier parameter names the file to which data is copied. The<br />
named file must be a tape file for which the run of the calling program has write<br />
privileges. See 2.3 for a detailed description of this parameter.<br />
5.4.5. User Descriptor Data<br />
The user descriptor data parameter is currently unused and must be null.<br />
5.4.6. Return Entry<br />
This function produces one return entry that gives information about the placement of<br />
the logical file on the destination SAF.<br />
The return entry for this function is the same as for COPY_RAF_SAF. See 5.2.6.<br />
5–32 7830 9796–013
5.4.7. Descriptor Return Area<br />
Copying Between Files<br />
The descriptor return area parameter returns the description of the logical file that this<br />
function reads from the source tape file. See 5.3.5 for a full description of this<br />
parameter.<br />
5.4.8. Work Area<br />
The size of the work area that the calling program provides for PCFP affects the<br />
performance of the COPY_SAF_RAF function. Because a large file cannot fit in main<br />
memory, this function copies a file one buffer at a time. The size of each buffer is<br />
between 1 and 16 mass storage tracks. I/O is most efficient with large buffers, so PCFP<br />
allocates the largest buffers possible within the work area that the calling program<br />
provides.<br />
The following formula indicates the number of words of work area that PCFP requires so<br />
that buffers N tracks in size (1 ≤ N ≤ 16) are allocated:<br />
Work Area Size = 800 + (3700 * N)<br />
The minimum work area size for this function (4,500 words) allows PCFP to allocate<br />
buffers one track in size. The maximum work area size for this function (60,000 words)<br />
allows PCFP to allocate buffers 16 tracks in size. There is no advantage to the calling<br />
program supplying this function with a work area larger than this maximum.<br />
If you expect to use the COPY_SAF_RAF function in the calling program to copy only<br />
small files (less than 50 tracks), a small work area size (1 to 4 tracks) is acceptable.<br />
However, if you expect that the files the calling program copies with this function might<br />
be large, a work area large enough for buffers 8 to 16 tracks in size is recommended.<br />
The larger the buffer size you allow, the faster the copy operation will complete. For<br />
very large files, always use the maximum work area size.<br />
In addition to performance considerations, the work area must be large enough to allow<br />
buffers at least as large as the size of the physical blocks read from the source file and<br />
written to the destination file. The work area is used most effectively if the buffer size is<br />
a multiple of the physical block size. For example, if the physical block is 4 tracks, the<br />
size of the work area must be at least 15,600 words (800 + 3700*4). A work area with a<br />
size of 15,600, 30,400, 45,200, or 60,000 words is most effective.<br />
7830 9796–013 5–33
Copying Between Files<br />
5–34 7830 9796–013
Section 6<br />
Acquiring Program File Information<br />
This section describes the following five functions that obtain information about the<br />
contents of a program file.<br />
• Acquire Basic Program File Information (ACQ_BASIC_PF_INFO)<br />
• Acquire Element Information (ACQ_ELT_INFO)<br />
• Acquire Relocatable Entry Point Information (ACQ_REL_EP_INFO)<br />
• Acquire Object Module Entry Point Information (ACQ_OM_EP_INFO)<br />
• Acquire Procedure Information (ACQ_PROC_INFO)<br />
These functions operate on only sector-addressable mass storage files that have been<br />
formatted as program files.<br />
6.1. Acquire Basic Program File Information<br />
(ACQ_BASIC_PF_INFO)<br />
The ACQ_BASIC_PF_INFO function returns global information about a specified program<br />
file. The information returned is not associated with particular elements, entry points, or<br />
procedures in the program file. Specifically, this function returns the following<br />
information:<br />
• An indication if this is an empty file that can be initialized as a program file<br />
• Next available mass storage location for element text<br />
• Amount of mass storage occupied by tables of contents in the program file<br />
• Amount of mass storage occupied by the text of all elements in the program file<br />
• Amount of mass storage occupied by the text of deleted elements in the program<br />
file<br />
• Number of undeleted elements of each type (absolute, omnibus, relocatable,<br />
symbolic) in the program file<br />
• Number of deleted elements (of all types) in the program file<br />
• Sequence number of last undeleted absolute element in the program file<br />
• Amount of mass storage occupied by the undeleted element with the largest<br />
amount of text<br />
• Number of undeleted and deleted symbolic elements of procedure subtype<br />
7830 9796–013 6–1
Acquiring Program File Information<br />
• Number of undeleted symbolic elements of procedure subtype<br />
• Number of undeleted and deleted four-word COBOL procedure table entries<br />
• Number of undeleted and deleted 8-word COBOL procedure table entries<br />
• Number of undeleted elements that will be updated if this file is processed with the<br />
PACK_PF function (see 8.4 for a description of the PACK_PF function)<br />
• Amount of mass storage that will be copied if this file is processed with the<br />
PACK_PF function<br />
• The type of program file (PF, LPF, standard LEPF, or large LEPF)<br />
• The following information for the element table of contents, each procedure table of<br />
contents, and the relocatable entry point table of contents:<br />
− The number of entries currently in the table (both deleted and undeleted entries)<br />
− The number of additional entries the table can hold at its currently allocated size<br />
(for the COBOL procedure table of contents, PCFP assumes maximum-size<br />
entries when it computes this value)<br />
Note: This information is not returned for the object module entry point table of<br />
contents, because, for this table, it is prohibitively expensive to determine the number of<br />
entries, and there is no limit to the number of additional entries that the table can hold.<br />
6.1.1. Parameters<br />
The ACQ_BASIC_PF_INFO function has the following parameters, each of which is<br />
described in the following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Work Area<br />
6–2 7830 9796–013
6.1.2. Function Packet<br />
Acquiring Program File Information<br />
The structure of the ACQ_BASIC_PF_INFO function packet is defined in element<br />
FP$ACQPFINF. See Figure 6–1.<br />
GENERIC PART<br />
0 a b<br />
1 NEXT_TEXT_LOCATION<br />
2 TOC_SIZE<br />
3 TEXT_SIZE<br />
4 LAST_ABS_SEQ_NUM<br />
5 ELT_NUM_ENTRIES ELT_OPEN_ENTRIES<br />
6 MASM_PROC_NUM_ENTRIES MASM_PROC_OPEN_ENTRIES<br />
7 COBOL_PROC_NUM_ENTRIES COBOL_PROC_OPEN_ENTRIES<br />
8 FTN_PLS_PROC_NUM_ENTRIES FTN_PLS_PROC_OPEN_ENTRIES<br />
9 REL_EP_NUM_ENTRIES REL_EP_OPEN_ENTRIES<br />
10 NUM_ABS_ELTS NUM_OMN_ELTS<br />
11 NUM_REL_ELTS NUM_SYM_ELTS<br />
12 NUM_DELETED_ELTS<br />
13 DEAD_SPACE<br />
14 LARGEST_UNDELETED_TEXT_SIZE<br />
15 NUM_PROC_ELTS NUM_UNDELETED_PROC_ELTS<br />
16 NUM_4_WORD_COBOL_PROC_ENTRIES NUM_8_WORD_COBOL_PROC_ENTRIES<br />
17 PACK_PF_NUM_ELTS_TO_UPDATE PROGRAM_FILE_TYPE<br />
18 PACK_PF_TEXT_SIZE_TO_COPY<br />
Figure 6–1. ACQ_BASIC_PF_INFO Function Packet Items<br />
7830 9796–013 6–3
Acquiring Program File Information<br />
Item Descriptions<br />
INTERFACE_LEVEL<br />
Contained in the GENERIC PART of the function packet and indicates the level of the<br />
packet. The calling program should set this item to the value<br />
FP_INTERFACE_LEVEL_2. If this item is set to FP_INTERFACE_LEVEL_1, the item<br />
EMPTY_FILE and the items in words 14 – 18 will not be returned by the function.<br />
Data Type: unsigned integer<br />
a = GET_SUMMARY_INFO<br />
Indicates whether PCFP computes values for the following items:<br />
• NUM_ABS_ELTS<br />
• NUM_OMN_ELTS<br />
• NUM_REL_ELTS<br />
• NUM_SYM_ELTS<br />
• NUM_DELETED_ELTS<br />
• DEAD_SPACE<br />
• LARGEST_UNDELETED_TEXT_SIZE<br />
• NUM_PROC_ELTS<br />
• NUM_UNDELETED_PROC_ELTS<br />
• PACK_PF_NUM_ELTS_TO_UPDATE<br />
• PACK_PF_TEXT_SIZE_TO_COPY<br />
If GET_SUMMARY_INFO = FALSE, a value of zero is returned for each of these<br />
items. (Computation of these values is optional because of the extra overhead<br />
involved in determining them.)<br />
Data Type: condition<br />
Note: All remaining items in this function packet contain return values.<br />
6–4 7830 9796–013
= EMPTY_FILE<br />
Acquiring Program File Information<br />
Indicates if this is an empty file that can be initialized as a program file by the PCFP<br />
CHG_FILE, COPY_ELT, COPY_RAF_OMN_ELT, or COPY_RAF_SYM_ELT functions.<br />
This item is returned only when INTERFACE_LEVEL has a value of at least<br />
FP_INTERFACE_LEVEL_2.<br />
When error code 2602 (fp_err_empty_file) is returned in ERROR_CODE in the<br />
GENERIC PART of the function packet, this item and PROGRAM_FILE_TYPE are still<br />
returned and should be interpreted as follows:<br />
− If EMPTY_FILE is TRUE, this file is empty and it can be initialized as a program<br />
file. Item PROGRAM_FILE_TYPE will have a value of NONE.<br />
− If EMPTY_FILE is FALSE, this file is already a program file, but it does not<br />
contain any elements. Item PROGRAM_FILE_TYPE will specify the type. This<br />
file cannot be initialized as a program file unless it is erased with the PCFP<br />
ERS_RAF function or the FURPUR @ERS command.<br />
Data Type: condition<br />
NEXT_TEXT_LOCATION<br />
Indicates the location (in words) where the text of the next element added to the<br />
program file is written.<br />
Data Type: unsigned integer, returned<br />
TOC_SIZE<br />
Indicates the amount of mass storage (in words) currently occupied by the tables of<br />
contents in the program file.<br />
Data Type: unsigned integer, returned<br />
TEXT_SIZE<br />
Indicates the amount of mass storage (in words) currently occupied by the text of all<br />
elements and all Object Module Entry Point Tables in the program file.<br />
Data Type: unsigned integer, returned<br />
LATEST_ABS_SEQ_NUM<br />
Indicates the sequence number of the latest undeleted absolute element in the<br />
program file. A value of zero implies either that the file contains no absolute<br />
elements or that the latest absolute element in the program file is marked deleted.<br />
Data Type: unsigned integer, returned<br />
7830 9796–013 6–5
Acquiring Program File Information<br />
ELT_NUM_ENTRIES<br />
Indicates the current number of entries in the element table of contents (deleted and<br />
undeleted).<br />
Data Type: unsigned integer, returned<br />
ELT_OPEN_ENTRIES<br />
Indicates the number of additional entries the element table of contents can contain<br />
at its currently allocated size. (See notes following item descriptions.)<br />
Data Type: unsigned integer, returned<br />
MASM_PROC_NUM_ENTRIES<br />
Indicates the current number of entries in the MASM procedure table of contents<br />
(deleted and undeleted).<br />
Data Type: unsigned integer, returned<br />
MASM_PROC_OPEN_ENTRIES<br />
Indicates the number of additional entries the MASM procedure table of contents<br />
can contain at its currently allocated size. (See notes following item descriptions.)<br />
Data Type: unsigned integer, returned<br />
COBOL_PROC_NUM_ENTRIES<br />
Indicates the current number of entries in the COBOL procedure table of contents<br />
(deleted and undeleted).<br />
Data Type: unsigned integer, returned<br />
COBOL_PROC_OPEN_ENTRIES<br />
Indicates the number of additional entries the COBOL procedure table of contents<br />
can contain at its currently allocated size. (See notes following item descriptions.)<br />
Data Type: unsigned integer, returned<br />
FTN_PLS_PROC_NUM_ENTRIES<br />
Indicates the current number of entries in the FORTRAN-PLUS procedure table of<br />
contents (deleted and undeleted).<br />
Data Type: unsigned integer, returned<br />
6–6 7830 9796–013
FTN_PLS_PROC_OPEN_ENTRIES<br />
Acquiring Program File Information<br />
Indicates the number of additional entries the FORTRAN-PLUS procedure table of<br />
contents can contain at its currently allocated size. (See notes following item<br />
descriptions.)<br />
Data Type: unsigned integer, returned<br />
REL_EP_NUM_ENTRIES<br />
Indicates the current number of entries in the relocatable entry point table of<br />
contents (deleted and undeleted).<br />
Data Type: unsigned integer, returned<br />
REL_EP_OPEN_ENTRIES<br />
Indicates the number of additional entries the relocatable entry point table of<br />
contents can contain at its currently allocated size. (See notes following item<br />
descriptions.)<br />
Data Type: unsigned integer, returned<br />
NUM_ABS_ELTS<br />
Indicates the number of undeleted absolute elements in the program file. Has a<br />
value of zero if the calling program set GET_SUMMARY_INFO = FALSE.<br />
Data Type: unsigned integer, returned<br />
NUM_OMN_ELTS<br />
Indicates the number of undeleted omnibus elements in the program file. Has a<br />
value of zero if the calling program set GET_SUMMARY_INFO = FALSE.<br />
Data Type: unsigned integer, returned<br />
NUM_REL_ELTS<br />
Indicates the number of undeleted relocatable elements in the program file. Has a<br />
value of zero if the calling program set GET_SUMMARY_INFO = FALSE.<br />
Data Type: unsigned integer, returned<br />
NUM_SYM_ELTS<br />
Indicates the number of undeleted symbolic elements in the program file. Has a<br />
value of zero if the calling program set GET_SUMMARY_INFO = FALSE.<br />
Data Type: unsigned integer, returned<br />
7830 9796–013 6–7
Acquiring Program File Information<br />
NUM_DELETED_ELTS<br />
Indicates the number of deleted elements of all types in the program file. Has a<br />
value of zero if the calling program set GET_SUMMARY_INFO = FALSE.<br />
Data Type: unsigned integer, returned<br />
DEAD_SPACE<br />
Indicates the amount of mass storage (in words) currently occupied by the text of all<br />
deleted elements and all Object Module Entry Point Tables in the program file. Has<br />
a value of zero if the calling program set GET_SUMMARY_INFO = FALSE.<br />
Data Type: unsigned integer, returned<br />
Note: All remaining items in this function packet are returned only when<br />
INTERFACE_LEVEL has a value of at least FP_INTERFACE_LEVEL_2.<br />
LARGEST_UNDELETED_TEXT_SIZE<br />
Indicates the amount of mass storage (in words) occupied by the text of the<br />
undeleted element with the largest amount of text. Has a value of zero if the calling<br />
program set GET_SUMMARY_INFO = FALSE.<br />
Data Type: unsigned integer, returned<br />
NUM_PROC_ELTS<br />
Indicates the number of symbolic procedure elements (subtypes ASMP, COBP,<br />
FORP, and PSP) in the program file (deleted and undeleted). Has a value of zero if<br />
the calling program set GET_SUMMARY_INFO = FALSE.<br />
Data Type: unsigned integer, returned<br />
NUM_UNDELETED_PROC_ELTS<br />
Indicates the number of undeleted symbolic procedure elements (subtypes ASMP,<br />
COBP, FORP, and PSP) in the program file. Has a value of zero if the calling program<br />
set GET_SUMMARY_INFO = FALSE.<br />
Data Type: unsigned integer, returned<br />
NUM_4_WORD_COBOL_PROC_ENTRIES<br />
Indicates the number of four-word COBOL procedure table entries in the program<br />
file (deleted and undeleted).<br />
Data Type: unsigned integer, returned<br />
6–8 7830 9796–013
NUM_8_WORD_COBOL_PROC_ENTRIES<br />
Acquiring Program File Information<br />
Indicates the number of 8-word COBOL procedure table entries in the program file<br />
(deleted and undeleted).<br />
Data Type: unsigned integer, returned<br />
PACK_PF_NUM_ELTS_TO_UPDATE<br />
Indicates the number of undeleted elements in the program file that would be<br />
updated if this file were processed with the PACK_PF function. See C.1 for a<br />
description of how this value affects PACK_PF function performance. Has a value of<br />
zero if the calling program set GET_SUMMARY_INFO = FALSE.<br />
Data Type: unsigned integer, returned<br />
PROGRAM_FILE_TYPE<br />
Indicates the type of the program file.<br />
Data Type: value-list<br />
NONE = 0<br />
PF = 1<br />
LPF = 2<br />
The file is not a program file. Returned when EMPTY_FILE is TRUE.<br />
The file is a standard program file (PF).<br />
The file is a large program file (LPF).<br />
STANDARD_LEPF = 3<br />
The file is a standard capacity, large element program file (standard LEPF).<br />
LARGE_LEPF = 4<br />
The file is a large capacity, large element program file (large LEPF).<br />
UNSUPPORTED = 6<br />
The file is a nonstandard program file.<br />
When error code 2602 (fp_err_empty_file) is returned in ERROR_CODE in the GENERIC<br />
PART of the function packet, this item is still returned. See EMPTY_FILE for a detailed<br />
explanation.<br />
7830 9796–013 6–9
Acquiring Program File Information<br />
PACK_PF_TEXT_SIZE_TO_COPY<br />
Indicates the amount of mass storage (in words) that would be copied if this file<br />
were processed with the PACK_PF function. See C.1 for a description of how this<br />
value affects PACK_PF function performance. Has a value of zero if the calling<br />
program set GET_SUMMARY_INFO = FALSE.<br />
Data Type: unsigned integer, returned<br />
Notes: The following points apply to each item that returns the number of available<br />
entries in a table of contents:<br />
• For a standard program file, if a table is empty (current number of entries is zero), the<br />
value that PCFP returns for the number of available entries in the table is also zero<br />
even though in most cases entries can be added to the table.<br />
• For a standard program file, PCFP calculates the number of available entries by<br />
assuming that all tables that are currently empty remain empty. If an entry is added<br />
later to a table that is currently empty, the number of entries available in other tables<br />
might be significantly reduced.<br />
• For a large program file, all tables have fixed sizes and a fixed maximum number of<br />
entries. PCFP calculates the number of available entries by subtracting from the<br />
fixed maximum the number of entries currently in the table.<br />
• Some tables (for example, the COBOL procedure table) have variable-length entries.<br />
PCFP calculates the number of available entries by assuming entries of maximum<br />
size.<br />
6.1.3. File Identifier<br />
The file identifier parameter names the file from which information is to be acquired.<br />
The named file must be a program file on sector-addressable mass storage for which the<br />
calling program has read privileges. See 2.3 for a description of this parameter.<br />
6.1.4. Work Area<br />
The ACQ_BASIC_PF_INFO function operates with any work area greater than or equal to<br />
the minimum size of 1,000 words. When the calling program sets<br />
GET_SUMMARY_INFO = FALSE, this function never uses a work area larger than this<br />
minimum. When the calling program sets GET_SUMMARY_INFO = TRUE, the function<br />
works more efficiently with larger work area sizes. The actual memory usable by the<br />
function varies with the size of the program file on which it operates. This function can<br />
make effective use of about 200 + 10*N words, where N is the number of elements<br />
(deleted and undeleted) in the program file. Thus, a work area size larger than the<br />
minimum is used with a program file containing more than 80 elements. The maximum<br />
size work area is used for program files containing about 2,000 or more elements.<br />
6–10 7830 9796–013
Acquiring Program File Information<br />
6.2. Acquire Element Information (ACQ_ELT_INFO)<br />
The ACQ_ELT_INFO function acquires information from a program file about one or<br />
more elements that meet conditions specified by the calling program. At a minimum,<br />
this function returns to the calling program the name, version, type, subtype, and<br />
sequence number of all elements that it selects. This function can select both undeleted<br />
and deleted elements.<br />
The element attributes by which PCFP can select elements are described in the<br />
definition of the function packet. Supplying a value for any attribute further restricts the<br />
set of elements PCFP selects. The calling program may supply values for as few or as<br />
many of these attributes as it requires.<br />
When PCFP selects a list of elements, it assumes no default selection criteria. Unless<br />
the calling program explicitly specifies a particular attribute, all values of that attribute are<br />
assumed to qualify. For example, if the calling program must limit the search to a<br />
particular type of element, it must specify an element type. If the calling program<br />
specifies no selection criteria, PCFP selects all elements in the program file.<br />
In some cases, a program may need to acquire more information about elements than<br />
their names, versions, types, subtypes, and sequence numbers. A notable example of<br />
this is the @PRT,TL capability of FURPUR. For this reason, the ACQ_ELT_INFO function<br />
also provides for the return of more extensive information. The full list of information<br />
obtainable is described in 6.2.4. It includes all information about elements that can be<br />
obtained using the FURPUR @PRT,TL command.<br />
The ACQ_ELT_INFO function has an option for limiting the number of element entries<br />
returned to a specified maximum. If more element entries than the maximum qualify,<br />
PCFP does not return the excess to the calling program.<br />
6.2.1. Parameters<br />
The ACQ_ELT_INFO function has the following parameters, each of which is described<br />
in the following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Return Entry<br />
• Work Area<br />
7830 9796–013 6–11
Acquiring Program File Information<br />
6.2.2. Function Packet<br />
0<br />
1<br />
2<br />
3<br />
4<br />
5<br />
10<br />
11<br />
12<br />
13<br />
6 a b c d<br />
The structure of the ACQ_ELT_INFO function packet is defined in element<br />
FP$ACQELTINF. See Figure 6–2.<br />
GENERIC PART<br />
RETURN-INFORMATION PART<br />
ELT_NAME<br />
ELT_VERSION<br />
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<br />
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<br />
9 f f f f f f f f f f f f f f f f f f CHAR_TYPE<br />
MIN_DATE_TIME<br />
MAX_DATE_TIME<br />
14 MIN_SEQ_NUM<br />
15 MAX_SEQ_NUM<br />
16 MIN_SIZE<br />
17 MAX_SIZE<br />
18 DELETION INFO_DETAIL<br />
19 NUM_SELECTED<br />
20<br />
…<br />
23<br />
Figure 6–2. ACQ_ELT_INFO Function Packet Items<br />
6–12 7830 9796–013<br />
…
Item Descriptions<br />
ELT_NAME<br />
Acquiring Program File Information<br />
Indicates name or pattern of the name of the elements to be selected. The value<br />
the calling program supplies for this item may contain the question mark ( ? ) and the<br />
asterisk ( * ) wild-card characters as described in 2.6. A null value indicates the<br />
elements are to be selected without regard to their names.<br />
Data Type: characters (12)<br />
ELT_VERSION<br />
Indicates version or pattern of the version of the elements to be selected. The value<br />
the calling program supplies for this item may contain the question mark ( ? ) and the<br />
asterisk ( * ) wild-card characters as described in 2.6. A null value indicates the<br />
elements are to be selected without regard to their versions.<br />
Data Type: characters (12)<br />
a = ABS_TYPE<br />
Indicates whether absolute elements are to be selected.<br />
Data Type: condition<br />
b = OMN_TYPE<br />
Indicates whether omnibus elements are to be selected.<br />
Data Type: condition<br />
c = REL_TYPE<br />
Indicates whether relocatable elements are to be selected.<br />
Data Type: condition<br />
d = SYM_TYPE<br />
Indicates whether symbolic elements are to be selected.<br />
Data Type: condition<br />
If items ABS_TYPE, OMN_TYPE, REL_TYPE, and SYM_TYPE are all FALSE, PCFP<br />
selects elements regardless of their types.<br />
7830 9796–013 6–13
Acquiring Program File Information<br />
e = OMN_SYM_SUBTYPE array (0:71)<br />
Indicates which omnibus and symbolic element subtypes PCFP selects. Each item<br />
in this array occupies a single bit. If the calling program sets any entries in this array<br />
to TRUE (1), PCFP limits the omnibus and symbolic elements it selects to those that<br />
have a numeric subtype corresponding to a TRUE entry. If the calling program sets<br />
no item in the array to TRUE, PCFP selects omnibus and symbolic elements<br />
regardless of subtype. This item applies only to symbolic and omnibus elements;<br />
this item does not affect the selection of elements of other types.<br />
Data Type: condition array<br />
f = ABS_SUBTYPE array (0:17)<br />
Indicates which absolute element subtypes PCFP selects. Each item in this array<br />
occupies a single bit. If the calling program sets any entries in this array to TRUE (1),<br />
PCFP limits the absolute elements it selects to those that have a numeric subtype<br />
corresponding to a TRUE entry. If the calling program sets no item in the array to<br />
TRUE, PCFP selects absolute elements regardless of subtype. This item applies<br />
only to absolute elements; this item does not affect the selection of elements of<br />
other types.<br />
Data Type: condition array<br />
CHAR_TYPE<br />
Indicates whether PCFP selects only ASCII or Fieldata elements, or if PCFP selects<br />
elements regardless of this attribute. This item applies only to symbolic elements;<br />
this item does not affect the selection of elements of other types.<br />
Data Type: value-list<br />
BOTH = 0<br />
ASCII = 1<br />
Fieldata = 2<br />
MIN_DATE_TIME<br />
Indicates whether PCFP selects elements with or without regard to a minimum date<br />
and time. If this item is nonzero, PCFP selects only elements with a date and time<br />
of creation greater than or equal to that specified. If this item is zero, PCFP selects<br />
elements without regard to a minimum date and time.<br />
Data Type: date-time<br />
6–14 7830 9796–013
MAX_DATE_TIME<br />
Acquiring Program File Information<br />
Indicates whether PCFP selects elements with or without regard to a maximum date<br />
and time. If this item is nonzero, PCFP selects only elements with a date and time<br />
of creation less than or equal to that specified. If this item is zero, PCFP selects<br />
elements without regard to a maximum date and time.<br />
Data Type: date-time<br />
MIN_SEQ_NUM<br />
Indicates whether PCFP selects elements with or without regard to a minimum<br />
sequence number. If this item is nonzero, PCFP selects only elements with a<br />
sequence number greater than or equal to that specified. If this item is zero, PCFP<br />
selects elements without regard to a minimum sequence number.<br />
Data Type: unsigned integer<br />
MAX_SEQ_NUM<br />
Indicates whether PCFP selects elements with or without regard to a maximum<br />
sequence number. If this item is nonzero, PCFP selects only elements with a<br />
sequence number less than or equal to that specified. If this item is zero, PCFP<br />
selects elements without regard to a maximum sequence number.<br />
If both MAX_SEQ_NUM and MIN_SEQ_NUM have the same nonzero value, PCFP<br />
selects at most one element.<br />
Data Type: unsigned integer<br />
MIN_SIZE<br />
Indicates whether PCFP selects elements with or without regard to a minimum text<br />
size. If this item is nonzero, PCFP selects only elements with a word size greater<br />
than or equal to that specified. If this item is zero, PCFP selects elements without<br />
regard to a minimum size.<br />
Data Type: unsigned integer<br />
MAX_SIZE<br />
Indicates whether elements are selected with or without regard to a maximum text<br />
size. If this item is nonzero, PCFP selects only elements with a word size less than<br />
or equal to that specified. If this item is zero, PCFP selects elements without regard<br />
to a maximum size.<br />
Data Type: unsigned integer<br />
7830 9796–013 6–15
Acquiring Program File Information<br />
DELETION<br />
Indicates whether PCFP selects elements regardless of whether or not they are<br />
deleted, or if PCFP selects only deleted or only undeleted elements.<br />
Data Type: value-list<br />
UNDELETED = 0<br />
Indicates that PCFP selects only undeleted elements.<br />
DELETED = 1<br />
Indicates that PCFP selects only deleted elements.<br />
BOTH = 2<br />
INFO_DETAIL<br />
Indicates that PCFP selects all elements regardless of whether or not they are<br />
deleted.<br />
Indicates the amount of information PCFP returns for each element it selects.<br />
Data Type: value-list<br />
SHORT = 0<br />
Indicates that for each element that PCFP selects, it returns only the following<br />
items: RESULT_INDICATOR, ELT_NAME, ELT_VERSION, ELT_TYPE,<br />
ELT_SUBTYPE, SEQ_NUM.<br />
LONG = 1<br />
Indicates that PCFP returns all information described in 6.2.4 for each element.<br />
NUM_SELECTED<br />
Indicates how many elements PCFP selected.<br />
Data Type: unsigned integer, returned<br />
6–16 7830 9796–013
6.2.3. File Identifier<br />
Acquiring Program File Information<br />
The file identifier parameter names the file from which information is to be acquired.<br />
The named file must be a program file on sector-addressable mass storage for which the<br />
calling program has read privileges. See 2.3 for a description of this parameter.<br />
6.2.4. Return Entry<br />
PCFP returns to the calling program one of the following entries for each element<br />
selected. The number of these entries produced is given by item NUM_RTN_ENTRIES<br />
in the generic part of the function packet.<br />
The structure for the return entry is defined in element FP$RTN$ELT. See<br />
Figure 6–3.<br />
0 RESULT_INDICATOR<br />
1<br />
2 ELT_NAME<br />
3<br />
4<br />
5 ELT_VERSION<br />
6<br />
7 SEQ_NUM ELT_TYPE aa<br />
8 ELT_SUBTYPE_NAME<br />
9 a b c d e f<br />
10 CREATE_DATE_TIME<br />
11<br />
12 TEXT_LOCATION<br />
13 TEXT_SIZE<br />
Figure 6–3. The First 14 Words of the Return Entry<br />
Words 14 and 15 of the return entry depend on the value of ELT_TYPE. Following are<br />
the possible overlays.<br />
7830 9796–013 6–17
Acquiring Program File Information<br />
Possible Overlays for Words 14 and 15 of the Return Entry<br />
Overlay used when ELT_TYPE = ABS:<br />
14 j k l m n<br />
15 NUM_PROG_BANKS NUM_COMMON_BANKS<br />
Overlay used when ELT_TYPE = OMN:<br />
14 APPLICATION_VALUE<br />
15<br />
Overlay used when ELT_TYPE = REL:<br />
14 PREAMBLE_SIZE<br />
15 PREAMBLE_LOCATION<br />
Overlay used when ELT_TYPE = SYM:<br />
14 TEXT_TYPE MAX_CYCLE<br />
15 CURRENT_CYCLE NUM_CYCLES<br />
Words 8 – 15 are present only when INFO_DETAIL = LONG in the function packet.<br />
Item Descriptions<br />
RESULT_INDICATOR<br />
Indicates whether PCFP successfully completed the operation for this element, and<br />
provides an explanation if it did not. For the ACQ_ELT_INFO, the value of this item<br />
is always FP_ERR_NONE (0).<br />
Data Type: ELMS condition-id<br />
ELT_NAME<br />
Indicates the name of the element.<br />
Data Type: characters (12)<br />
ELT_VERSION<br />
Indicates the version of the element. If the element has no version, the item<br />
contains all spaces.<br />
Data Type: characters (12)<br />
6–18 7830 9796–013
SEQ_NUM<br />
Acquiring Program File Information<br />
Indicates the sequence number of the element in the table of contents of the<br />
program file.<br />
Data Type: integer<br />
ELT_TYPE<br />
Indicates the type of the element.<br />
Data Type: value-list<br />
ABS =1<br />
OMN = 2<br />
REL = 3<br />
SYM = 4<br />
aa = OMN_SYM_SUBTYPE<br />
Indicates the subtype of the element. This item is applicable only for an omnibus or<br />
a symbolic element (ELT_TYPE = OMN or SYM).<br />
Data Type: value-list<br />
SYM = 0 FLT = 16 GSA = 32<br />
ELT = 1 PNC = 17 MSG = 33<br />
ASM = 2 TCL = 18 PRT = 34<br />
COB = 3 MSM = 19 RPG = 35<br />
FOR = 4 MSD = 20 ADA = 36<br />
ALG = 5 MAC = 21 PEER = 37<br />
MAP = 6 APT = 22 C = 38<br />
DOC = 7 PGA = 23 FHLL = 39<br />
SEC = 8 QLP = 24 LINK = 40<br />
SSG = 9 INL = 25 COM = 41<br />
APL = 10 DCL = 26 PADS = 42<br />
BAS = 11 SDL = 27 SSDP = 43<br />
LSP = 12 FDP = 28 FLDP = 44<br />
PLS = 13 PSP = 29 ASMP = 64<br />
PL1 = 14 PAS = 30 COBP = 65<br />
CTS =15 IPF = 31 FORP = 66<br />
7830 9796–013 6–19
Acquiring Program File Information<br />
aa = ABS_SUBTYPE (overlays OMN_SYM_SUBTYPE)<br />
Indicates the subtype of the element. This item is applicable only for an absolute<br />
element (ELT_TYPE = ABS).<br />
Data Type: value-list<br />
ABS = 0<br />
OM = 1<br />
SSD = 2<br />
ZM = 3<br />
BOM = 17<br />
The remaining items in the element return entry are present only if the calling program<br />
set INFO_DETAIL = LONG in the function packet.<br />
ELT_SUBTYPE_NAME<br />
Indicates the character mnemonic for the element subtype. This item has a value of<br />
all spaces when ELT_TYPE = REL.<br />
Data Type: characters (4)<br />
a = ELT_DELETED<br />
Indicates whether the element has been marked deleted.<br />
Data Type: condition<br />
b = ELT_IN_ERROR<br />
Indicates whether the element has been marked in error.<br />
Data Type: condition<br />
c = QUARTER_WORD_SENSITIVE<br />
Indicates whether the element has been marked as quarter-word sensitive.<br />
Data Type: condition<br />
d = THIRD_WORD_SENSITIVE<br />
Indicates whether the element has been marked as third-word sensitive.<br />
Data Type: condition<br />
6–20 7830 9796–013
e = ARITH_FAULT_NON_INTERRUPT<br />
Acquiring Program File Information<br />
Indicates whether the element has been marked for Arithmetic Fault Noninterrupt<br />
mode.<br />
Data Type: condition<br />
f = ARITH_FAULT_COMPATIBLE<br />
Indicates whether the element has been marked for Arithmetic Fault Compatibility<br />
mode.<br />
Data Type: condition<br />
CREATE_DATE_TIME<br />
Indicates the date and time the element was created.<br />
Data Type: date-time<br />
TEXT_LOCATION<br />
Indicates the starting word address of the text of the element in the program file.<br />
Data Type: unsigned integer<br />
TEXT_SIZE<br />
Indicates the size of the text of the element in words. If the element is a relocatable<br />
element, the PREAMBLE_SIZE is included in the TEXT_SIZE. If the element text<br />
size is an illegal value, TEXT_SIZE has a value of -1.<br />
Data Type: integer<br />
The following items overlay each other in each element return entry. The items that<br />
exist in a particular entry depend upon the type of the element (ELT_TYPE) described by<br />
the entry. The following items exist only when ELT_TYPE = ABS:<br />
j = DUAL_PSR<br />
Indicates whether the absolute element requires a dual PSR machine to execute.<br />
Data Type: condition<br />
k = ZERO_FILL_SUPPRESS<br />
Indicates whether the Exec zero-fills uninitialized areas of this absolute element at<br />
the start of its execution.<br />
Data Type: condition<br />
7830 9796–013 6–21
Acquiring Program File Information<br />
l = NO_START_ADDRESS<br />
Indicates whether this absolute element has no start address.<br />
Data Type: condition<br />
m = REAL_TIME_LOAD<br />
Indicates whether this element requires real time load when it executes.<br />
Data Type: condition<br />
n = BLOCK_SIZE_64<br />
Indicates whether this absolute element has a block size of 64 words instead of 512<br />
words.<br />
Data Type: condition<br />
NUM_PROG_BANKS<br />
Indicates the number of program banks contained in the absolute element.<br />
Data Type: unsigned integer<br />
NUM_COMMON_BANKS<br />
Indicates the number of common banks referenced by the absolute element. This<br />
item is applicable only for absolute elements with subtype ABS(0).<br />
Data Type: unsigned integer<br />
The following item exists only when ELT_TYPE = OMN:<br />
APPLICATION_VALUE.<br />
Application dependent value for this omnibus element.<br />
Data Type: unsigned integer<br />
The following items exist only when ELT_TYPE = REL:<br />
PREAMBLE_SIZE<br />
Indicates the size in words of the preamble of the relocatable element. If the<br />
element preamble size is an illegal value, PREAMBLE_SIZE has a value of -1.<br />
Data Type: integer<br />
6–22 7830 9796–013
PREAMBLE_LOCATION<br />
Acquiring Program File Information<br />
Indicates the starting word address of the preamble of the relocatable element in the<br />
program file.<br />
Data Type: unsigned integer<br />
The following items exist only when ELT_TYPE = SYM:<br />
TEXT_TYPE<br />
Indicates whether the symbolic element contains ASCII or Fieldata text.<br />
Data Type: value-list<br />
ASCII = 1<br />
Fieldata = 2<br />
MAX_CYCLES<br />
Indicates the maximum number of symbolic cycles the element may contain.<br />
Data Type: unsigned integer range (1 to 63)<br />
CURRENT_CYCLE<br />
Indicates the number of the most recent symbolic cycle in the element.<br />
Data Type: unsigned integer range (0 to 62)<br />
NUM_CYCLES<br />
6.2.5. Work Area<br />
Indicates the actual number of symbolic cycles currently in the element.<br />
Data Type: unsigned integer range (1 to 63)<br />
The ACQ_ELT_INFO function works with any work area greater than or equal to the<br />
minimum size of 1,000 words. The function can work more efficiently with larger work<br />
area sizes. The actual memory usable by the function varies with the size of the<br />
program file on which it operates. This function can make effective use of about 200 +<br />
10*N words, where N is the number of elements (deleted and undeleted) in the program<br />
file. Thus, a work area size larger than the minimum is useful with a program file<br />
containing more than 80 elements. The maximum size work area is useful only for a<br />
program file containing about 2,000 elements or more.<br />
7830 9796–013 6–23
Acquiring Program File Information<br />
6.3. Acquire Relocatable Entry Point Information<br />
(ACQ_REL_EP_INFO)<br />
The ACQ_REL_EP_INFO function returns information from the relocatable entry point<br />
table in a program file. (A different function ACQ_OM_EP_INFO returns information<br />
from the object-module entry point table.) This function can return both undeleted and<br />
deleted relocatable entry points.<br />
This function returns the following information about each relocatable entry point it<br />
selects:<br />
• Entry point name<br />
• Sequence number of element containing the entry point<br />
• Name and version of element containing the entry point (optional)<br />
• Deletion indicator<br />
This function can select relocatable entry points based on any combination of the<br />
following attributes:<br />
• Entry point name<br />
• Name of relocatable element containing the entry point<br />
• Version of relocatable element containing the entry point<br />
Each attribute for which the calling program supplies a value further restricts the set of<br />
entry points this function selects. The calling program may supply values for as few or<br />
as many of these attributes as it requires. If the calling program supplies no values for<br />
any attributes, all relocatable entry points in the program file are selected.<br />
The following options are provided with this function:<br />
• Select the undeleted entry points, deleted entry points, or both.<br />
• Limit the number of relocatable entry points acquired to a specified maximum. If<br />
more entry points than the maximum qualify, PCFP does not return the excess to<br />
the calling program.<br />
• For each entry point selected, either return or do not the name and version of the<br />
element containing the entry point.<br />
6.3.1. Parameters<br />
The ACQ_REL_EP_INFO function has the following parameters, each of which is<br />
described in the following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Return Entry<br />
• Work Area<br />
6–24 7830 9796–013
6.3.2. Function Packet<br />
Acquiring Program File Information<br />
The structure of the ACQ_REL_EP_INFO function packet is defined in element<br />
FP$ACQRELEP. See Figure 6–4.<br />
GENERIC PART<br />
RETURN-INFORMATION PART<br />
0 MAX_COUNT INFO_DETAIL<br />
1 DELETION<br />
2<br />
3 EP_NAME<br />
4<br />
5<br />
6 ELT_NAME<br />
7<br />
8<br />
9 ELT_VERSION<br />
10<br />
11 NUM_SELECTED<br />
Item Descriptions<br />
MAX_COUNT<br />
Figure 6–4. ACQ_REL_EP_INFO Function Packet Items<br />
Indicates the maximum number of entry points this function acquires. A value of<br />
zero indicates no maximum.<br />
Data Type: integer<br />
INFO_DETAIL<br />
Data Type: value-list<br />
SHORT = 0<br />
Indicates that the following information only is to be returned for each entry<br />
point: entry point name, sequence number of element containing the entry point,<br />
and deletion indicator.<br />
7830 9796–013 6–25
Acquiring Program File Information<br />
LONG = 1<br />
DELETION<br />
Indicates that the name and version of the element containing the entry point<br />
are to be returned, in addition to the information listed above.<br />
Data Type: value-list<br />
UNDELETED = 0<br />
Indicates that this function selects only undeleted entry points.<br />
DELETED = 1<br />
Indicates that this function selects only deleted entry points.<br />
BOTH = 2<br />
EP_NAME<br />
Indicates that this function selects entry points whether or not they are deleted.<br />
Indicates the name or pattern of the name of the relocatable entry points that this<br />
function selects. The value the calling program supplies for this item may contain<br />
the question mark ( ? ) and the asterisk ( * ) wild-card characters as described in 2.6.<br />
A null value indicates the entry points are selected without regard to their names.<br />
Data Type: characters (12)<br />
ELT_NAME<br />
Indicates the name or pattern of the name of the relocatable elements containing the<br />
entry points that this function selects. The value that the calling program selects for<br />
this item may contain the question mark ( ? ) and the asterisk ( * ) wild-card<br />
characters as described in 2.6. A null value indicates the entry points are selected<br />
without regard to the name of the element containing them.<br />
Data Type: characters (12)<br />
ELT_VERSION<br />
Indicates the version or pattern of the version of the relocatable elements containing<br />
the entry points that this function selects. The value the calling program supplies for<br />
this item may contain the question mark ( ? ) and the asterisk ( * ) wild-card<br />
characters as described in 2.6. A null value indicates the entry points are selected<br />
without regard to the version of the element containing them.<br />
Data Type: characters (12)<br />
6–26 7830 9796–013
NUM_SELECTED<br />
Indicates how many entry points the function selected.<br />
Data Type: unsigned integer, returned<br />
6.3.3. File Identifier<br />
Acquiring Program File Information<br />
The file identifier parameter names the file from which information is to be acquired.<br />
The named file must be a program file on sector-addressable mass storage for which the<br />
calling program has read privileges. See 2.3 for a description of this parameter.<br />
6.3.4. Return Entry<br />
One of the following entries is returned for each relocatable entry point the function<br />
selects. The number of these entries produced is given by item NUM_RTN_ENTRIES in<br />
the function packet. This return entry structure is defined in element FP$RTN$RELEP.<br />
See Figure 6–5.<br />
0 a SEQ_NUM<br />
1<br />
2 EP_NAME<br />
3<br />
4<br />
5 ELT_NAME<br />
6<br />
7<br />
8 ELT_VERSION<br />
9<br />
Figure 6–5. ACQ_REL_EP_INFO Return Entry Items<br />
Items ELT_NAME and ELT_VERSION are present only when the calling program set<br />
INFO_DETAIL = LONG in the function packet.<br />
Item Descriptions<br />
a = DELETE_FLAG<br />
Indicates whether the entry point is deleted.<br />
Data Type: condition<br />
7830 9796–013 6–27
Acquiring Program File Information<br />
SEQ_NUM<br />
Indicates the sequence number of the element that contains the entry point.<br />
Data Type: unsigned integer<br />
EP_NAME<br />
Indicates the name of the entry point.<br />
Data Type: characters (12)<br />
The following items are included in the long form only.<br />
ELT_NAME<br />
Indicates the name of the relocatable element that contains the entry point.<br />
Data Type: characters (12)<br />
ELT_VERSION<br />
6.3.5. Work Area<br />
Indicates the version of the relocatable element that contains the entry point.<br />
Data Type: characters (12)<br />
The ACQ_REL_EP_INFO function works with any work area greater than or equal to the<br />
minimum size of 2,000 words. This function works more efficiently with larger work<br />
area sizes. The actual memory usable by the function varies with the size of the<br />
program file. In approximate terms, this function can make efficient use of 400 + 4*EP<br />
+ 10*N words, where EP is the number of relocatable entry points and N is the number<br />
of elements (deleted and undeleted) in the program file. Thus, a work area size larger<br />
than the minimum is useful, for example, with a program file containing more than 350<br />
relocatable entry points in 20 elements. For most situations, the minimum work area<br />
size of 2,000 words gives acceptable performance.<br />
6–28 7830 9796–013
6.4. Acquire Object Module Entry Point<br />
Information (ACQ_OM_EP_INFO)<br />
Acquiring Program File Information<br />
The ACQ_OM_EP_INFO function returns information from the object module entry point<br />
table in a program file. (A different function ACQ_REL_EP_INFO returns information<br />
from the relocatable entry point table.)<br />
This function returns the following information about each object-module entry point it<br />
selects:<br />
• Entry point name (Although object-module entry point names can be any length, this<br />
function returns only the first 32 characters.)<br />
• Length of full entry point name<br />
• Sequence number of object-module absolute element containing the entry point<br />
• Index of the entry point in the object-module absolute element that contains it<br />
• Indication of whether or not the entry point has been prepped<br />
• Date and time the entry point was created<br />
• The entry point type (common-block, code, constant, data, or fixed-gate)<br />
• Standard calling sequence conformance of the entry point (none, loose, or strict)<br />
• Text type of the entry point (ASCII or Kanji)<br />
• Name and version of the object-module absolute element containing the entry point<br />
(optional)<br />
This function can select object module entry points based on any combination of the<br />
following attributes:<br />
• Entry point name<br />
• Name of element containing the entry point<br />
• Version of element containing the entry point<br />
• Entry point type<br />
• Standard calling sequence conformance of the entry point<br />
• Text-type of the entry point<br />
• Date and time the entry point was created<br />
Each attribute for which the calling program supplies a value further restricts the set of<br />
entry points that this function selects. The calling program may supply values for as few<br />
or as many of these attributes as it requires. If the calling program supplies no values for<br />
any attributes, all object-module entry points in the program file are selected.<br />
7830 9796–013 6–29
Acquiring Program File Information<br />
The following options are provided with this function:<br />
• Limit the number of object-module entry points acquired to a specified maximum. If<br />
more entry points than the maximum qualify, PCFP does not return the excess to<br />
the calling program.<br />
• For each entry point selected, either return the name and version of the element<br />
containing the entry point, or not.<br />
6.4.1. Parameters<br />
The ACQ_OM_EP_INFO function has the following parameters, each of which is<br />
described in the following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Return Entry<br />
• Work Area<br />
6–30 7830 9796–013
6.4.2. Function Packet<br />
Acquiring Program File Information<br />
The structure of the ACQ_OM_EP_INFO function packet is defined in element<br />
FP$ACQOMEP. See Figure 6–6.<br />
GENERIC PART<br />
RETURN-INFORMATION PART<br />
0 MAX_COUNT INFO_DETAIL<br />
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<br />
2 TEXT_TYPE SCF_CONFORMANCE<br />
3<br />
4<br />
5<br />
6<br />
7<br />
8<br />
9<br />
10<br />
11<br />
12<br />
13<br />
14<br />
…<br />
21<br />
22<br />
…<br />
29<br />
MIN_DATE_TIME<br />
MAX_DATE_TIME<br />
ELT_NAME<br />
ELT_VERSION<br />
EP_NAME<br />
30 NUM_SELECTED<br />
Figure 6–6. ACQ_OM_EP_INFO Function Packet Items<br />
7830 9796–013 6–31<br />
…
Acquiring Program File Information<br />
Item Descriptions<br />
MAX_COUNT<br />
Indicates the maximum number of entry points this function returns. A value of zero<br />
indicates no maximum.<br />
Data Type: integer<br />
INFO_DETAIL<br />
Data Type: value-list<br />
SHORT = 0<br />
Indicates that PCFP does not return the name and version of the element<br />
containing each entry point to the calling program.<br />
LONG = 1<br />
Indicates that PCFP returns the name and version of the element containing<br />
each entry point to the calling program.<br />
a = EP_TYPE array (0:35)<br />
Indicates the types of entry points this function selects. Each item in this array<br />
occupies a single bit. If the calling program sets any entries in this array to TRUE (1),<br />
this function selects only object-module entry points with a type corresponding to a<br />
TRUE item. If the calling program sets no item in the array to TRUE, the function<br />
selects object-module entry points regardless of type.<br />
Data Type: condition array<br />
TEXT_TYPE<br />
Indicates the text type of the object module entry points that the function selects.<br />
Data Type: value-list<br />
NO_CONSTRAINT = 0<br />
Causes selection of entry points regardless of text type.<br />
ASCII = 1<br />
Limits entry points selected to those with ASCII names.<br />
Kanji = 3<br />
Limits entry points selected to those with Kanji names.<br />
6–32 7830 9796–013
SCS_CONFORMANCE<br />
Acquiring Program File Information<br />
Indicates the standard calling sequence conformance of the object-module entry<br />
points that the function selects.<br />
Data Type: value-list<br />
NO_CONSTRAINT = 0<br />
Causes selection of entry points regardless of SCS conformance.<br />
NONE = 1<br />
Limits entry points selected to those with no conformance.<br />
LOOSE = 16<br />
Limits entry points selected to those with loose conformance.<br />
STRICT = 17<br />
Limits entry points selected to those with strict conformance.<br />
MIN_DATE_TIME<br />
Indicates whether PCFP selects entry points with or without regard to a minimum<br />
date and time of creation. If this item is nonzero, PCFP selects only object-module<br />
entry points with a date and time of creation greater than or equal to that specified.<br />
If this item is zero, PCFP selects entry points without regard to a minimum date and<br />
time.<br />
Data Type: date-time<br />
MAX_DATE_TIME<br />
Indicates whether PCFP selects entry points with or without regard to a maximum<br />
date and time of creation. If this item is not zero, PCFP selects object-module entry<br />
points with a date and time less than or equal to that specified. If this item is zero,<br />
PCFP selects entry points without regard to a maximum date and time.<br />
Data Type: date-time<br />
ELT_NAME<br />
Indicates the name or pattern of the name of the object-module absolute elements<br />
containing the entry points that this function selects. The value the calling program<br />
supplies for this item may contain the question mark ( ? ) and the asterisk ( * )<br />
wild-card characters as described in 2.6. A null value indicates the entry points are<br />
selected without regard to the name of the element containing them.<br />
Data Type: characters (12)<br />
7830 9796–013 6–33
Acquiring Program File Information<br />
ELT_VERSION<br />
Indicates the version or pattern of the version of the object-module absolute<br />
elements containing the entry points that this function selects. The value the calling<br />
program supplies for this item may contain the question mark ( ? ) and the asterisk<br />
( * ) wild-card characters as described in 2.6. A null value indicates the entry points<br />
are selected without regard to the version of the element containing them.<br />
Data Type: characters (12)<br />
EP_NAME<br />
Indicates the name or pattern of the name of the object-module entry points that this<br />
function selects. This item is case sensitive: uppercase and lowercase letters are<br />
not equivalent. The value the calling program supplies for this item may contain the<br />
question mark ( ? ) and the asterisk ( * ) wild-card characters as described in 2.6. A<br />
null value indicates the entry points are selected without regard to their names. If<br />
the calling program supplies a nonnull value for this item, it must also set<br />
TEXT_TYPE = ASCII. Object-module entry point names greater than 32 characters<br />
cannot match any specified EP_NAME, even if wild-card characters are used.<br />
Data Type: characters (32)<br />
NUM_SELECTED<br />
Indicates how many entry points the function selected.<br />
Data Type: unsigned integer, returned<br />
6.4.3. File Identifier<br />
The file identifier parameter names the file from which information is to be acquired.<br />
The named file must be a program file on sector-addressable mass storage for which the<br />
calling program has read privileges. See 2.3 for a description of this parameter.<br />
6–34 7830 9796–013
6.4.4. Return Entry<br />
Acquiring Program File Information<br />
One of the following entries is returned for each object-module entry point the<br />
ACQ_OM_EP_INFO function selects. The number of these entries produced is given by<br />
item NUM_RTN_ENTRIES in the function packet. This return entry structure is defined<br />
in element FP$RTN$OMEP. See Figure 6–7.<br />
0 SEQ_NUM EP_INDEX<br />
1 CREATE_DATE_TIME<br />
2<br />
3 EP_TYPE b c<br />
4 TEXT_TYPE PREPPED EP_NAME_LENGTH<br />
5<br />
6<br />
.. EP_NAME<br />
21<br />
22<br />
23 ELT_NAME<br />
24<br />
25<br />
26 ELT_VERSION<br />
27<br />
Figure 6–7. ACQ_OM_EP_INFO Return Entry Items<br />
Items ELT_NAME and ELT_VERSION are present only when the calling program set<br />
INFO_DETAIL = LONG in the function packet.<br />
Item Descriptions<br />
SEQ_NUM<br />
Indicates the sequence number of the element that contains the entry point.<br />
Data Type: unsigned integer<br />
EP_INDEX<br />
Indicates the index of the entry point in the object-module element that contains it.<br />
Data Type: unsigned integer<br />
7830 9796–013 6–35
Acquiring Program File Information<br />
CREATE_DATE_TIME<br />
Indicates the date and time that the entry point was created.<br />
Data Type: date-time<br />
EP_TYPE<br />
Indicates the definition type of the entry point.<br />
Data Type: value-list<br />
UNKNOWN = 0<br />
COMMON_BLOCK_EP = 16<br />
CODE_EP = 17<br />
CONSTANT_EP = 18<br />
DATA_EP = 19<br />
FIXED_GATE_EP = 20<br />
b = VISIBILITY<br />
Indicates whether the entry point is internal or external. (Currently this function only<br />
returns entry points with VISIBILITY = EXT.)<br />
Data Type: value-list<br />
EXT = 16<br />
INT = 17<br />
c = SCS_CONFORMANCE<br />
Indicates the standard calling sequence conformance of the entry point.<br />
Data Type: value-list<br />
UNDEFINED = 0<br />
NONE = 1<br />
LOOSE = 16<br />
STRICT = 17<br />
TEXT_TYPE<br />
Indicates the text type of the entry point name.<br />
Data Type: value-list<br />
ASCII = 1<br />
Kanji = 3<br />
6–36 7830 9796–013
PREPPED<br />
Acquiring Program File Information<br />
Indicates whether the object module entry point has been prepped.<br />
Data Type: value-list<br />
UNPREPPED = 0<br />
PREPPED = 1<br />
EP_NAME_LENGTH<br />
Contains the complete length of the entry point name in characters (ASCII or Kanji).<br />
Data Type: unsigned integer<br />
EP_NAME<br />
Contains up to the first 32 characters of the entry point name. This item is case<br />
sensitive: uppercase and lowercase letters are not equivalent in object module entry<br />
point names. If EP_NAME_LENGTH is greater than 32 characters, only the first 32<br />
characters are returned. The type of characters returned is indicated by TEXT_TYPE.<br />
Data Type: characters (32)<br />
(For the C language, this item is a union containing character arrays named ASCII and<br />
KANJI.)<br />
The following items are included in the long form only:<br />
ELT_NAME<br />
Indicates the name of the object-module absolute element that contains the entry<br />
point.<br />
Data Type: characters (12)<br />
ELT_VERSION<br />
Indicates the version of the object-module absolute element that contains the entry<br />
point.<br />
Data Type: characters (12)<br />
7830 9796–013 6–37
Acquiring Program File Information<br />
6.4.5. Work Area<br />
The ACQ_OM_EP_INFO function works with any work area greater than or equal to the<br />
minimum size of 2,000 words. This function works more efficiently with larger work<br />
area sizes. The actual memory usable by the function varies with the size of the<br />
program file. In approximate terms, this function can make efficient use of 200 + 28 *<br />
EP + 10 * N words, where EP is the number of object-module entry points and N is the<br />
number of elements (deleted and undeleted) in the program file. Thus, a work area size<br />
larger than the minimum is useful, for example, with a program file containing more than<br />
50 object-module entry points in 40 elements. For most situations, the minimum work<br />
area size of 2,000 words gives acceptable performance.<br />
The total of WORK_AREA_SIZE and RTN_AREA_SIZE should not exceed approximately<br />
227,000 words. This is the approximate maximum size that can be specified for this<br />
function, where the minimum relative address is MIN_DATA_ADDR_WITH_LINK and the<br />
maximum relative address is MAX_DATA_ADDR, as contained in the copy/include<br />
element FP$DEFS.<br />
6–38 7830 9796–013
6.5. Acquire Procedure Information<br />
(ACQ_PROC_INFO)<br />
Acquiring Program File Information<br />
The ACQ_PROC_INFO function returns information from a specified procedure table in a<br />
program file. Any of the procedure tables in a program file can be handled by this<br />
function. (There are three procedure tables: assembler, COBOL, and FORTRAN-PLUS.)<br />
For each procedure selected, the ACQ_PROC_INFO function returns the following<br />
information:<br />
• Procedure name<br />
• Sequence number of the symbolic element containing the procedure<br />
• Name and version of the symbolic element containing the procedure (optional)<br />
• Mass-storage address of the start of the procedure in the program file<br />
• Text type of procedure (ASCII or Fieldata)<br />
• Deletion indicator<br />
This function can select procedures based on any combination of the following<br />
attributes:<br />
• Procedure name<br />
• Name of symbolic element containing the procedure<br />
• Version of symbolic element containing the procedure<br />
Each attribute for which the calling program supplies a value further restricts the set of<br />
entry points that this function selects. The calling program may supply values for as few<br />
or as many of these attributes as it requires. If the calling program specifies no values<br />
for any attributes, all procedures in the table are specified by the calling program.<br />
The following options are provided with this function:<br />
• Acquire information from the assembler procedure table, the COBOL procedure<br />
table, or the FORTRAN-PLUS procedure table.<br />
• Select undeleted procedures, deleted procedures, or both.<br />
• Limit the number of procedure entries returned to a specified maximum. If more<br />
procedures than the maximum qualify, PCFP does not return the excess to the<br />
calling program.<br />
6.5.1. Parameters<br />
The ACQ_PROC_INFO function has the following parameters, each of which is<br />
described in the following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Return Entry<br />
• Work Area<br />
7830 9796–013 6–39
Acquiring Program File Information<br />
6.5.2. Function Packet<br />
The structure for ACQ_PROC_INFO function packet is defined in element<br />
FP$ACQPROC. See Figure 6–8.<br />
GENERIC PART<br />
RETURN-INFORMATION PART<br />
0 DELETION PROC_TABLE<br />
1 MAX_COUNT INFO_DETAIL<br />
2 PROC_NAME<br />
.. . . .<br />
8<br />
9 PROC_NAME<br />
10<br />
11 ELT_NAME<br />
12<br />
13<br />
14 ELT_VERSION<br />
15<br />
16 NUM_SELECTED<br />
Item Descriptions<br />
DELETION<br />
Figure 6–8. ACQ_PROC_INFO Function Packet Items<br />
Data Type: value-list<br />
UNDELETED = 0<br />
Indicates that this function selects only undeleted procedures.<br />
DELETED = 1<br />
Indicates that this function selects only deleted procedures.<br />
BOTH = 2<br />
Indicates that this function selects procedures whether or not they are deleted.<br />
6–40 7830 9796–013
PROC_TABLE<br />
Acquiring Program File Information<br />
Indicates the procedure table from which the function retrieves procedures.<br />
Data Type: value-list<br />
MASM_PROC = 2<br />
COBOL_PROC = 3<br />
FTN_PLS_PROC = 4<br />
MAX_COUNT<br />
Indicates the maximum number of procedure entries this function acquires. A value<br />
of zero indicates no maximum.<br />
Data Type: integer<br />
INFO_DETAIL<br />
Data Type: value-list<br />
SHORT = 0<br />
Indicates that PCFP does not return the name and version of the element<br />
containing each procedure.<br />
LONG = 1<br />
PROC_NAME<br />
Indicates that PCFP returns the name and version of the element containing<br />
each procedure.<br />
Indicates the name or the pattern of the name of the procedures that this function<br />
selects. The value the calling program supplies for this item may contain the<br />
question mark ( ? ) and asterisk ( * ) wild-card characters as described in 2.6. A null<br />
value indicates that procedures are selected without regard to their names. The<br />
value the calling program supplies for this item must not be longer than 12<br />
characters when PROC_TABLE = MASM_PROC or FTN_PLS_PROC.<br />
Data Type: characters (30)<br />
ELT_NAME<br />
Indicates the name or the pattern of the name of the elements containing the<br />
procedures that this function selects. The value the calling program supplies for this<br />
item may contain the question mark ( ? ) and the asterisk ( * ) wild-card characters as<br />
described in 2.6. A null value indicates that procedures are selected without regard<br />
to the name of the element containing them.<br />
Data Type: characters (12)<br />
7830 9796–013 6–41
Acquiring Program File Information<br />
ELT_VERSION<br />
Indicates the version or the pattern of the version of the elements containing the<br />
procedures that this function selects. The value the calling program supplies for this<br />
item may contain the question mark ( ? ) and the asterisk ( * ) wild-card characters as<br />
described in 2.6. A null value indicates that procedures are selected without regard<br />
to the version of the element containing them.<br />
Data Type: characters (12)<br />
NUM_SELECTED<br />
Indicates how many procedures the function selected.<br />
Data Type: unsigned integer, returned<br />
6.5.3. File Identifier<br />
The file identifier parameter names the file from which information is to be acquired.<br />
The named file must be a program file on sector-addressable mass storage for which the<br />
calling program has read privileges. See 2.3 for a description of this parameter.<br />
6.5.4. Return Entry for MASM, FORTRAN, and PLUS<br />
Procedures<br />
This function returns one of two information structures depending on the value of<br />
PROC_TABLE in the function packet. It is important that the structure definition you<br />
include in your program matches the structure requested from PCFP in the function<br />
packet.<br />
When the calling program sets PROC_TABLE = MASM_PROC or FTN_PLS_PROC, this<br />
function returns one of the following entries for each procedure selected (see<br />
Figure 6–9). The number of these entries the function produces is given by the item<br />
NUM_RTN_ENTRIES in the function packet.<br />
6–42 7830 9796–013
This return-entry structure is defined in element FP$RTN$PROC.<br />
Acquiring Program File Information<br />
0 a TEXT_TYPE SEQ_NUM<br />
1 PROC_LOCATION<br />
2<br />
3 PROC_NAME<br />
4<br />
5<br />
6 ELT_NAME<br />
7<br />
8<br />
9 ELT_VERSION<br />
10<br />
Figure 6–9. ACQ_PROC_INFO Return Entry Structure When<br />
PROC_TABLE = MASM_PROC or FTN_PLS_PROC<br />
Items ELT_NAME and ELT_VERSION are returned only when the calling program set<br />
INFO_DETAIL = LONG in the function packet.<br />
Item Descriptions<br />
a = DELETE_FLAG<br />
Indicates whether the procedure is deleted.<br />
Data Type: condition<br />
TEXT_TYPE<br />
Indicates whether the procedure images are ASCII or Fieldata.<br />
Data Type: value-list<br />
ASCII = 1<br />
Fieldata = 2<br />
SEQ_NUM<br />
Indicates the sequence number of the element that contains the procedure.<br />
Data Type: unsigned integer<br />
7830 9796–013 6–43
Acquiring Program File Information<br />
PROC_LOCATION<br />
Indicates the word address of the start of the procedure within the program file.<br />
Data Type: unsigned integer<br />
PROC_NAME<br />
Indicates the name of the procedure.<br />
Data Type: characters (12)<br />
The following items are included only when INFO_DETAIL = LONG in the function<br />
packet.<br />
ELT_NAME<br />
Indicates the name of the element that contains the procedure.<br />
Data Type: characters (12)<br />
ELT_VERSION<br />
Indicates the version of the element that contains the procedure.<br />
Data Type: characters (12)<br />
6.5.5. Return Entry for COBOL Procedures<br />
This function returns one of two information structures depending on the value of<br />
PROC_TABLE in the function packet. It is important that the structure definition you<br />
include in your program matches the structure requested from PCFP in the function<br />
packet.<br />
When the calling program sets PROC_TABLE = COBOL_PROC, this function returns one<br />
of the following entries for each procedure selected (see Figure 6–10). The number of<br />
these entries the function produced is given by the item NUM_RTN_ENTRIES in the<br />
function packet.<br />
This return entry structure is defined in element FP$RTN$PROC.<br />
6–44 7830 9796–013
Acquiring Program File Information<br />
0 a TEXT_TYPE SEQ_NUM<br />
1 PROC_LOCATION<br />
2 PROC_NAME<br />
. . . . .<br />
8<br />
9 PROC_NAME<br />
10<br />
11 ELT_NAME<br />
12<br />
13<br />
14 ELT_VERSION<br />
15<br />
Figure 6–10. ACQ_PROC_INFO Return Information Structure When<br />
PROC_TABLE = COBOL PROC<br />
Items ELT_NAME and ELT_VERSION are present only when the calling program set<br />
INFO_DETAIL = LONG in the function packet.<br />
Item Descriptions<br />
a = DELETE_FLAG<br />
Indicates whether the procedure is deleted.<br />
Data Type: condition<br />
TEXT_TYPE<br />
Indicates whether the procedure images are ASCII or Fieldata.<br />
Data Type: value-list<br />
ASCII = 1<br />
Fieldata = 2<br />
SEQ_NUM<br />
Indicates the sequence number of the element that contains the procedure.<br />
Data Type: unsigned integer<br />
7830 9796–013 6–45
Acquiring Program File Information<br />
PROC_LOCATION<br />
Indicates the word address of the start of the procedure within the program file.<br />
Data Type: unsigned integer<br />
PROC_NAME<br />
Indicates the name of the procedure.<br />
Data Type: characters (30)<br />
The following items are included only when INFO_DETAIL = LONG in the function<br />
packet.<br />
ELT_NAME<br />
Indicates the name of the element that contains the procedure.<br />
Data Type: characters (12)<br />
ELT_VERSION<br />
6.5.6. Work Area<br />
Indicates the version of the element that contains the procedure.<br />
Data Type: characters (12)<br />
The ACQ_PROC_INFO function works with any work area greater than or equal to the<br />
minimum size of 2,000 words. This function works more efficiently with larger work<br />
area sizes. The actual memory usable by the function varies with the size of the<br />
program file. In approximate terms, this function can make efficient use of 400 + 8*P +<br />
10*N words, where P is the number of procedures (deleted and undeleted) and N is the<br />
number of elements (deleted and undeleted) in the program file. Thus, a work area size<br />
larger than the minimum is useful, for example, with a program file containing 125<br />
procedures in 60 elements. For most situations, the minimum work area size of 2,000<br />
words gives acceptable performance.<br />
6–46 7830 9796–013
Section 7<br />
Copying Program File Elements<br />
This section describes the following five functions that copy an element from or to a<br />
program file.<br />
• Copy Elements (COPY_ELT)<br />
• Copy Symbolic Element to RAF (COPY_SYM_ELT_RAF)<br />
• Copy RAF to Symbolic Element (COPY_RAF_SYM_ELT)<br />
• Copy Omnibus Element to RAF (COPY_OMN_ELT_RAF)<br />
• Copy RAF to Omnibus Element (COPY_RAF_OMN_ELT)<br />
7.1. Copy Elements (COPY_ELT)<br />
The COPY_ELT function copies one or more elements from one program file to another<br />
program file. The copied elements have the same type, subtype, and ASCII/Fieldata<br />
indicator in the destination file they had in the source file.<br />
This function corresponds to the FURPUR @COPY command with some combination of<br />
the A, O, P, R, and S options.<br />
You can select the elements you want copied based on name, version, type, subtype, or<br />
some combination of these. You can specify part of a name and/or version, as described<br />
in 2.6. You cannot select deleted elements.<br />
The COPY_ELT function provides the following options:<br />
• Require PCFP to assign the destination file exclusively or not.<br />
• Initialize an empty destination file as a PF, LPF, standard LEPF, large LEPF, or as the<br />
same program file type as the source file.<br />
• Have each element retain its original name and version after it is copied, or give each<br />
element a new name and/or version as specified by the calling program. If a new<br />
name or version is specified, it may include wild-card characters indicating that the<br />
corresponding characters from the original name or version are to be retained. See<br />
2.6 for details.<br />
• If an element to be copied has the same name, version, and type as an element<br />
already in the destination file, do one of the following:<br />
− Delete the original and complete the copy.<br />
− Retain the original and do not complete the copy.<br />
7830 9796–013 7–1
Copying Program File Elements<br />
− Delete the original and complete the copy only if the element being copied has a<br />
later date and time of creation.<br />
• For each symbolic element, copy either all symbolic cycles or only a single specified<br />
symbolic cycle. In the latter case, you can specify the cycle number as either an<br />
absolute number or a number relative to the latest cycle.<br />
• Either retain the old date and time of creation for each element copied or assign the<br />
current date and time into those fields.<br />
• Return name, version, type, and result indicator for<br />
− Each element that was selected and successfully copied<br />
− Each element that was selected but not copied<br />
− Each element that was selected, whether it was copied or not<br />
− No elements<br />
In all cases, the COPY_ELT function returns the number of elements it selected for<br />
copying, the number it successfully copied, and the number it did not copy.<br />
When this function copies one or more relocatable elements into the destination<br />
program file, it removes any relocatable entry point table that previously existed in the<br />
program file. However, when this function copies one or more object module absolute<br />
elements into a program file, it does not remove any existing object module entry point<br />
tables.<br />
When this function copies one or more procedure symbolic elements to the destination<br />
file and all symbolic cycles are specified, it also copies all procedure table entries<br />
associated with those elements.<br />
When this function causes one or more procedure symbolic elements to be deleted from<br />
the destination file, it also deletes any procedure entries associated with those<br />
elements.<br />
7.1.1. Parameters<br />
The COPY_ELT function has the following parameters, each of which is described in the<br />
following subsections:<br />
• Function Packet<br />
• Source File Identifier<br />
• Destination File Identifier<br />
• Return Entry<br />
• Work Area<br />
7–2 7830 9796–013
7.1.2. Function Packet<br />
0<br />
1<br />
2<br />
3<br />
4<br />
5<br />
10<br />
11<br />
12<br />
13<br />
14<br />
15<br />
6 a b c d<br />
Copying Program File Elements<br />
The structure of the function packet for COPY_ELT is defined in element FP$CPYELT.<br />
See Figure 7–1.<br />
GENERIC PART<br />
RETURN-INFORMATION PART<br />
ELT_NAME<br />
ELT_VERSION<br />
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 e<br />
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 e<br />
9 f f f f f f f f f f f f f f f f f f INIT_DEST_FILE<br />
DEST_ELT_NAME<br />
DEST_ELT_VERSION<br />
16 g h i ON_CONFLICT<br />
17 CYCLE_TYPE CYCLE_NUM<br />
18 INFO_TO_RETURN INFO_DETAIL<br />
19 NUM_SELECTED<br />
20 NUM_SUCCESSFUL<br />
21 NUM_FAILED<br />
Figure 7–1. COPY_ELT Function Packet Items<br />
7830 9796–013 7–3
Copying Program File Elements<br />
Item Descriptions<br />
ELT_NAME<br />
Indicates name or pattern of the name of the elements this function copies. The<br />
value the calling program supplies for this item may contain the question mark ( ? )<br />
and asterisk ( * ) wild-card characters as described in 2.6. A null value indicates the<br />
elements are to be copied without regard to element name.<br />
Data Type: characters (12)<br />
ELT_VERSION<br />
Indicates version or pattern of the version of the elements this function copies. The<br />
value the calling program supplies for this item may contain the question mark ( ? )<br />
and asterisk ( * ) wild-card characters as described in 2.6. A null value indicates the<br />
elements are to be copied without regard to version.<br />
Data Type: characters (12)<br />
a = ABS_TYPE<br />
Indicates whether absolute elements are to be copied.<br />
Data Type: condition<br />
b = OMN_TYPE<br />
Indicates whether omnibus elements are to be copied.<br />
Data Type: condition<br />
c = REL_TYPE<br />
Indicates whether relocatable elements are to be copied.<br />
Data Type: condition<br />
d = SYM_TYPE<br />
Indicates whether symbolic elements are to be copied.<br />
Data Type: condition<br />
If the calling program sets items ABS_TYPE, OMN_TYPE, REL_TYPE, and<br />
SYM_TYPE all to FALSE or all to TRUE, elements are copied regardless of their type.<br />
7–4 7830 9796–013
e = OMN_SYM_SUBTYPE array (0:71)<br />
Copying Program File Elements<br />
Indicates which subtypes of omnibus and symbolic elements this function copies.<br />
Each item in this array occupies a single bit. If the calling program sets any entries in<br />
this array to TRUE (1), only omnibus and symbolic elements that have a numeric<br />
subtype corresponding to a TRUE entry are copied. If the calling program sets no<br />
item in the array to TRUE, this function copies omnibus and symbolic elements<br />
regardless of subtype. This item applies only to symbolic and omnibus elements and<br />
does not affect the selection of elements of other types.<br />
Data Type: condition array<br />
f = ABS_SUBTYPE array (0:17)<br />
Indicates which subtypes of absolute elements this function copies. Each item in<br />
this array occupies a single bit. If the calling program sets any entries in this array to<br />
TRUE (1), only absolute elements that have a numeric subtype corresponding to a<br />
TRUE entry are copied. If the calling program sets no item in the array to TRUE, this<br />
function copies absolute elements regardless of subtype. This item applies only to<br />
absolute elements and does not affect the selection of elements of other types.<br />
Data Type: condition array<br />
INIT_DEST_FILE<br />
Indicates how PCFP should initialize an empty destination file.<br />
Data Type: value-list<br />
NONE = 0<br />
PF = 1<br />
This value must be specified if the destination file is not initially empty. If the<br />
destination file is empty, it will be initialized as a standard program file (PF).<br />
LPF = 2<br />
Initialize the destination file as a standard program file (PF).<br />
Initialize the destination file as a large program file (LPF).<br />
STANDARD_LEPF = 3<br />
Initialize the destination file as a standard capacity, large element program file<br />
(standard LEPF).<br />
LARGE_LEPF = 4<br />
Initialize the destination file as a large capacity, large element program file (large<br />
LEPF).<br />
7830 9796–013 7–5
Copying Program File Elements<br />
SOURCE_FILE_TYPE = 5<br />
Initialize the destination file as the same program file type as the source file.<br />
For values other than NONE, the destination file must be empty. Files are empty<br />
when initially created with @ASG or @CAT and when erased with the PCFP<br />
ERS_RAF function or the FURPUR @ERS command.<br />
DEST_ELT_NAME<br />
Indicates the name PCFP gives to the copied element in the destination file. The<br />
value the calling program supplies for this item may contain the question mark ( ? )<br />
wild-card character. PCFP replaces each question mark by the corresponding<br />
character in the original element name. If this value is null, the elements PCFP<br />
copies retain their original names.<br />
Data Type: characters (12)<br />
DEST_ELT_VERSION<br />
Indicates the version PCFP gives to the copied element in the destination file. The<br />
value the calling program supplies for this item may contain the question mark ( ? )<br />
wild-card character. Each question mark is replaced by the corresponding character<br />
in the original element version. If this value is null, the elements PCFP copies retain<br />
their original versions.<br />
Data Type: characters (12)<br />
g = EXCLUSIVE_ASSIGN<br />
Indicates whether or not PCFP must assign the destination file exclusively.<br />
Data Type: condition<br />
h = NEW_DATE_TIME<br />
Indicates whether each element being copied retains its old date and time of<br />
creation or changes to the date and time that the copy is performed.<br />
Data Type: condition<br />
i = COPY_CURRENT_CYCLE<br />
Indicates how the text of symbolic elements other than procedure elements is<br />
copied, when the text has an SDF type of general symbolic. When TRUE, only<br />
non-deleted records are copied to the destination file where they are identified as<br />
being added at cycle 0. When FALSE or when the element is a procedure element<br />
or when the SDF type is other than general symbolic, the copy is performed as<br />
described for CYCLE_TYPE and CYCLE_NUM.<br />
Data Type: condition<br />
7–6 7830 9796–013
ON_CONFLICT<br />
Copying Program File Elements<br />
Indicates what action PCFP takes for any element it attempts to copy that has the<br />
same name, version, and type as an element already in the destination file.<br />
Data Type: value-list<br />
DO_NOT_COPY = 0<br />
Indicates that PCFP not copy the element.<br />
DELETE_ORIGINAL = 1<br />
Indicates that PCFP delete the existing element with that name, version, and<br />
type from the destination file, and complete copying the file.<br />
COPY_IF_NEWER = 2<br />
CYCLE_TYPE<br />
Indicates that PCFP delete the existing element from the destination file and<br />
complete copying the element only if the date and time of the element being<br />
copied is later than that of the element already in the destination file.<br />
Indicates if CYCLE_NUM contains an absolute element-cycle value, a relative<br />
element-cycle value, or no element-cycle value. This item and CYCLE_NUM affect<br />
only the copying of symbolic elements.<br />
Data Type: value-list<br />
UNSPECIFIED = 0<br />
Indicates that PCFP copies all cycles of the symbolic elements that it selects. If<br />
this element is a procedure symbolic element, UNSPECIFIED must be selected<br />
if the associated procedure table entries are to be copied to the destination file.<br />
ABS = 1<br />
Indicates that for each symbolic element it selects PCFP copies only the specific<br />
absolute symbolic cycle indicated by CYCLE_NUM.<br />
REL = 2<br />
Indicates that for each symbolic element it selects PCFP copies only the specific<br />
relative symbolic cycle indicated by CYCLE_NUM.<br />
7830 9796–013 7–7
Copying Program File Elements<br />
CYCLE_NUM<br />
Indicates the specific cycle that PCFP copies for symbolic elements. If the calling<br />
program sets CYCLE_TYPE = UNSPECIFIED, it must set this item to 0. If the calling<br />
program sets CYCLE_TYPE = ABS, it must set this item to a value between 0 and 62<br />
inclusive. If the calling program sets CYCLE_TYPE = REL, it must set this item to a<br />
value between -62 and 0 inclusive. If a symbolic element PCFP selects for copying<br />
does not contain the cycle specified here, PCFP does not copy that element.<br />
Data Type: signed integer range (-62 through 62)<br />
INFO_TO_RETURN<br />
Indicates which elements selected by PCFP have individual information returned to<br />
the calling program.<br />
Data Type: value-list<br />
NONE = 0<br />
Indicates that PCFP returns individual information for no elements.<br />
ERROR_ONLY = 1<br />
Indicates that PCFP returns individual information only for each element it<br />
selected but did not copy.<br />
NONERROR_ONLY = 2<br />
Indicates that PCFP returns individual information for each element that it<br />
selected and copied successfully.<br />
ALL_INFO = 3<br />
INFO_DETAIL<br />
Indicates that PCFP returns individual information for each element it selected,<br />
whether or not it was copied.<br />
For each individual element for which PCFP returns information, indicates what parts<br />
of the element information PCFP returns. PCFP ignores this item if the calling<br />
program set INFO_TO_RETURN = NONE.<br />
Data Type: value-list<br />
SHORT = 0<br />
Indicates that for each element that has return information, PCFP returns only<br />
the following items: RESULT_INDICATOR, ELT_NAME, ELT_VERSION,<br />
ELT_TYPE, ELT_SUBTYPE, ELT_SEQ_NUM.<br />
7–8 7830 9796–013
LONG = 1<br />
Copying Program File Elements<br />
Indicates that PCFP returns all information described in 6.2.4 for each element.<br />
SUMMARY = 3<br />
Indicates that instead of returning individual information for each element, PCFP<br />
summarizes the information and returns it in a single summary entry, as<br />
described in 7.1.5.<br />
NUM_SELECTED<br />
Indicates the number of source file elements PCFP found that were not deleted and<br />
that matched function packet specifications for element name (ELT_NAME), element<br />
version (ELT_VERSION), element type (ABS_TYPE, OMN_TYPE, REL_TYPE or<br />
SYM_TYPE) and element subtype (OMN_SYM_SUBTYPE or ABS_SUBTYPE).<br />
Data Type: unsigned integer, returned<br />
NUM_SUCCESSFUL<br />
Indicates the number of elements PCFP actually copied.<br />
Data Type: unsigned integer, returned<br />
NUM_FAILED<br />
Indicates the number of source file elements selected by PCFP that were not copied<br />
to the destination file. The elements were not copied because the masking<br />
specified in destination element name (DEST_ELT_NAME) or destination version<br />
name (DEST_ELT_VERSION) created an illegal name, because the same element<br />
name, element version and element type already existed in the destination file and<br />
the ON_CONFLICT specification did not allow element deletion, or because the<br />
element did not match symbolic element cycle number specifications (CYCLE_TYPE<br />
and CYCLE_NUM). If the calling program requested return of error information, the<br />
reason that the element was not copied to the destination file is indicated by<br />
RESULT_INDICATOR in the return entry.<br />
Serious errors that cause termination of the COPY_ELT function are not counted in<br />
this item. These errors are reported in the generic part of the function packet, as<br />
described in 2.4.1.<br />
When the function completes successfully, NUM_SELECTED is equal to the sum of<br />
NUM_SUCCESSFUL and NUM_FAILED. When the function terminates because of<br />
an error during an element copy, NUM_SELECTED can be one greater than the sum<br />
of NUM_SUCCESSFUL and NUM_FAILED.<br />
Data Type: unsigned integer, returned<br />
7830 9796–013 7–9
Copying Program File Elements<br />
7.1.3. Source File Identifier<br />
The source file identifier parameter names the file from which elements are copied. The<br />
named file must be a program file on sector-addressable mass storage for which the<br />
calling program has read privileges. See 2.3 for a description of this parameter.<br />
7.1.4. Destination File Identifier<br />
The destination file identifier parameter names the file to which elements are copied.<br />
The named file must initially be either a program file or empty. It must reside on<br />
sector-addressable mass storage, and the calling program must have both read and write<br />
privileges for the file. See 2.3 for a description of this parameter.<br />
7.1.5. Return Entry<br />
When the function packet item INFO_DETAIL is set to SHORT or LONG, PCFP returns<br />
one entry for each element indicated by the function packet item INFO_TO_RETURN.<br />
See 6.2.4 for a description of these entries.<br />
For those elements that PCFP selected and was able to copy, PCFP sets the item<br />
RESULT_INDICATOR in the return entry to one of the following values:<br />
FP_ERR_NONE<br />
Indicates that PCFP copied the element successfully with no complications.<br />
FP_INFO_PROC_TOC_FULL<br />
Indicates that PCFP copied the element successfully, but was unable to insert some<br />
or all of the procedure entries associated with the element because the procedure<br />
table in the destination file is full. When this error is detected, the function is<br />
terminated.<br />
FP_INFO_PROC_TBL_ERR<br />
Indicates that PCFP copied the element successfully, but was unable to process<br />
some or all of the procedure entries associated with the element. When this error is<br />
detected, the function is terminated.<br />
For those elements that PCFP selected but was not able to copy, PCFP sets the item<br />
RESULT_INDICATOR to one of the following values:<br />
FP_WARN_ELT_CONFLICT<br />
Indicates that PCFP was not able to copy the element because the destination file<br />
already contains an element of the same type that has a name and version matching<br />
the name and version of the destination element. This value is returned only if the<br />
calling program set ON_CONFLICT = DO_NOT_COPY in the function packet.<br />
7–10 7830 9796–013
FP_WARN_ELT_NOT_NEWER<br />
Copying Program File Elements<br />
Indicates that PCFP was not able to copy the element because the destination file<br />
contains an element with the same name, version, and type, but with a date and<br />
time of creation that is more recent. This value is returned only if the calling program<br />
set ON_CONFLICT = COPY_IF_NEWER in the function packet.<br />
FP_WARN_NONEXISTENT_SYM_CYCLE<br />
Indicates that PCFP was not able to copy the symbolic element because the<br />
symbolic cycle specified by the calling program does not exist.<br />
FP_WARN_BAD_ELT_NAME<br />
Indicates that PCFP was not able to copy the element because the new name<br />
generated for it contains an embedded space.<br />
FP_WARN_BAD_ELT_VERSION<br />
Indicates that PCFP was not able to copy the element because the new version<br />
generated for it contains an embedded space.<br />
When the function packet item INFO_DETAIL is set to SUMMARY, PCFP returns a<br />
single entry summarizing the copy operations for elements indicated by the function<br />
packet item INFO_TO_RETURN. The item NUM_RTN_ENTRIES in the Return<br />
Information part of the function packet is set to 1.<br />
The structure for the return entry is defined in element FP$RTN$ELT. See Figure 7–2.<br />
0 TEXT_SIZE<br />
1 NUM_ELTS NUM_MASM_PROCS<br />
2 NUM_COBOL_PROCS NUM_FTN_PLS_PROCS<br />
3 NUM_REL_EPS NUM_OM_EPS<br />
4 NUM_ABS_ELTS NUM_OMN_ELTS<br />
5 NUM_REL_ELTS NUM_SYM_ELTS<br />
Item Descriptions<br />
TEXT_SIZE<br />
Figure 7–2. Summary Return Entry<br />
Indicates the total size of the text in words.<br />
Data type: integer<br />
NUM_ELTS<br />
Indicates the total number of elements of all types.<br />
7830 9796–013 7–11
Copying Program File Elements<br />
Data type: integer<br />
NUM_MASM_PROCS<br />
Indicates the total number of MASM procedures associated with symbolic elements<br />
with subtype ASMP (64).<br />
Data type: integer<br />
NUM_COBOL_PROCS<br />
Indicates the total number of COBOL procedures associated with symbolic elements<br />
with subtype COBP (65).<br />
Data type: integer<br />
NUM_FTN_PLS_PROCS<br />
Indicates the sum of the number of FORTRAN procedures associated with symbolic<br />
elements with subtype FORP (66) and the number of PLUS procedures associated<br />
with symbolic elements with subtype PSP (29).<br />
Data type: integer<br />
NUM_REL_EPS<br />
Indicates the total number of relocatable entry points associated with relocatable<br />
elements. This item will be zero for COPY_ELT.<br />
Data type: integer<br />
NUM_OM_EPS<br />
Indicates the total number of object module entry points associated with object<br />
module absolute elements. This item will be zero for COPY_ELT.<br />
Data type: integer<br />
NUM_ABS_ELTS<br />
Indicates the total number of absolute elements.<br />
Data type: integer<br />
NUM_OMN_ELTS<br />
Indicates the total number of omnibus elements.<br />
Data type: integer<br />
7–12 7830 9796–013
NUM_REL_ELTS<br />
Indicates the total number of relocatable elements.<br />
Data type: integer<br />
NUM_SYM_ELTS<br />
Indicates the total number of symbolic elements.<br />
Data type: integer<br />
7.1.6. Work Area<br />
Copying Program File Elements<br />
The COPY_ELT function works with any work area greater than or equal to the minimum<br />
size of 2,000 words. In many situations, this function works more efficiently with a<br />
larger work area size. The actual memory used by this function varies with the size of<br />
the program files it operates on, the number of elements it copies, and the text size of<br />
the largest element it copies. In approximate terms, the word size of the work area<br />
usable by the function is usually given by 125 + S + D + I + C, where<br />
S The source file buffer size. S can be approximated as 252 + (10 * J), where J is<br />
the number of deleted and undeleted elements in the source file. Acceptable<br />
performance can usually be achieved with the minimum size source file buffer<br />
(252 words).<br />
D The destination file buffer size. D can be approximated as 252 + (10 * (K + L)),<br />
where K is the initial number of deleted and undeleted elements in the destination<br />
file and L is the number of elements to copy from the source file to the<br />
destination file. Use the recommended size destination file buffer for optimum<br />
performance.<br />
I The input/output buffer size. I can be approximated as the smaller of 65,520 and<br />
M, where M is the size in words of the largest element to copy. The minimum<br />
size input/output buffer is 896 words. Acceptable performance can usually be<br />
achieved with a buffer size of four 1,792-word tracks (7,168 words).<br />
C The procedure table copy buffer size. C can be approximated as 3 + (3 * N),<br />
where N is the number of procedure elements to copy from the source file to the<br />
destination file. Use the recommended size procedure table copy buffer for<br />
optimum performance. If there are over 50 procedure elements to copy, at least<br />
150 words must be provided for this buffer.<br />
As described in 2.4.1, the total work area size plus the return area size cannot exceed<br />
approximately 238,000 words.<br />
For optimum performance of this function, ensure that the work area recommended for<br />
D and I is available. Sufficient work area for these two buffers is the most important<br />
factor in achieving optimum performance.<br />
7830 9796–013 7–13
Copying Program File Elements<br />
The maximum defined work area size of 74,000 words should provide adequate<br />
performance for nearly all combinations of source and destination file sizes. For some<br />
extremely large files, performance may be improved further by providing a work area<br />
size that is larger than the defined maximum, as indicated by the work area formula.<br />
When the maximum possible work area size (about 238,000) is specified and return area<br />
size is specified as zero, there is sufficient work area available to efficiently create a<br />
destination large program file of approximately 23,000 elements. This is less than the<br />
design maximum for large program files of 26,146 elements. The efficiency of copy<br />
operations decreases very significantly as the number of elements increases from<br />
approximately 23,000 toward the design maximum of 26,146. Likewise, for a<br />
destination file with approximately 23,000 elements, the efficiency of copy operations<br />
decreases significantly as the specified work area size decreases from the maximum<br />
possible size.<br />
7.2. Copy Symbolic Element to RAF<br />
(COPY_SYM_ELT_RAF)<br />
The COPY_SYM_ELT_RAF function copies a symbolic element from a program file into a<br />
mass storage random-access file. The content of the destination file following this<br />
function is SDF text.<br />
This function provides the following options:<br />
• Either requires the destination file to be empty initially (that is, have no mass storage<br />
allocated to it) or copies over anything already in the destination file.<br />
• Copies either the latest symbolic cycle or a specified symbolic cycle of the symbolic<br />
element being copied. In the latter case, the calling program can specify the cycle<br />
number as either an absolute number or a number relative to the latest cycle.<br />
7.2.1. Parameters<br />
The COPY_SYM_ELT_RAF function packet has the following parameters, each of which<br />
is described in the following subsections:<br />
• Function Packet<br />
• Source File Identifier<br />
• Destination File Identifier<br />
• Work Area<br />
7–14 7830 9796–013
7.2.2. Function Packet<br />
Copying Program File Elements<br />
The structure of the COPY_SYM_ELT_RAF function packet is defined in element<br />
FP$CPYSYMRAF. See Figure 7–3.<br />
0<br />
GENERIC PART<br />
1 ELT_NAME<br />
2<br />
3<br />
4 ELT_VERSION<br />
5<br />
6 ACTION<br />
7 CYCLE_TYPE CYCLE_NUM<br />
8 AMOUNT_COPIED<br />
Figure 7–3. COPY_SYM_ELT_RAF Function Packet Items<br />
Item Descriptions<br />
ELT_NAME<br />
Indicates the name of the element to be copied. A null value is not allowed for this<br />
item.<br />
Data Type: characters (12)<br />
ELT_VERSION<br />
Indicates the version of the element to be copied. A value of spaces indicates an<br />
element with no version. A null value is not allowed for this item.<br />
Data Type: characters (12)<br />
ACTION<br />
Indicates what action PCFP takes if the destination file already contains data.<br />
Data Type: value-list<br />
OVERCOPY = 0<br />
Indicates that PCFP copies the element text, overwriting the data previously in<br />
the destination file.<br />
7830 9796–013 7–15
Copying Program File Elements<br />
MUST_BE_EMPTY = 1<br />
CYCLE_TYPE<br />
Indicates that PCFP copies the element text only if the destination file is initially<br />
empty. This value requires the run of the calling program to have read privileges<br />
for the destination file.<br />
Indicates if CYCLE_NUM contains an absolute element-cycle value, a relative<br />
element-cycle value, or no element-cycle value.<br />
Data Type: value-list<br />
UNSPECIFIED = 0<br />
Indicates that PCFP copies the latest symbolic cycle of the symbolic element.<br />
ABS = 1<br />
Indicates that PCFP copies only the specific absolute symbolic cycle indicated by<br />
CYCLE_NUM.<br />
REL = 2<br />
CYCLE_NUM<br />
Indicates that PCFP copies only the specific relative symbolic cycle indicated by<br />
CYCLE_NUM.<br />
Indicates which cycle of the symbolic element PCFP copies. If the calling program<br />
sets CYCLE_TYPE = UNSPECIFIED, it must set CYCLE_NUM to a value of 0. If the<br />
calling program sets CYCLE_TYPE = ABS, it must set CYCLE_NUM to a value<br />
between 0 and 62 inclusive. If the calling program sets CYCLE_TYPE = REL, it must<br />
set CYCLE_NUM to a value between -62 and 0 inclusive. If the symbolic element<br />
does not contain the cycle specified here, PCFP does not copy the element.<br />
Data Type: signed integer range (-62 through 62)<br />
AMOUNT_COPIED<br />
Indicates the number of words of text PCFP copied to the destination file.<br />
Data Type: unsigned integer, returned<br />
7.2.3. Source File Identifier<br />
The source file identifier parameter names the file from which the element is to be<br />
copied. The named file must be a program file on sector-addressable mass storage for<br />
which the calling program has read privileges. See 2.3 for a description of this<br />
parameter.<br />
7–16 7830 9796–013
7.2.4. Destination File Identifier<br />
Copying Program File Elements<br />
The destination file identifier parameter names the file to which PCFP copies the<br />
element text. It must be a sector-addressable mass storage file for which the calling<br />
program has write privileges. See 2.3 for a full description of this parameter.<br />
7.2.5. Work Area<br />
This function works with any work area greater than or equal to the minimum size of<br />
1,000 words. However, the function can work more efficiently with larger work area<br />
sizes. The actual memory usable by the function varies with the size of the program file<br />
operated on and the size of the element text copied. This function can make effective<br />
use of about (200 + 10*N + S) words, where N is the number of elements (deleted and<br />
undeleted) in the source program file, and S is the word size of the element text copied.<br />
For most situations, the minimum size work area gives acceptable performance.<br />
7.3. Copy RAF to Symbolic Element<br />
(COPY_RAF_SYM_ELT)<br />
The COPY_RAF_SYM_ELT function creates a symbolic element in a program file from<br />
the contents of a mass storage random-access file. The content of the source file must<br />
be SDF text.<br />
The COPY_RAF_SYM_ELT function provides the following options:<br />
• Require PCFP to assign the destination file exclusively or not.<br />
• Initialize an empty destination file as a PF, LPF, standard LEPF, or large LEPF.<br />
• If a symbolic element with the same name and version already exists in the program<br />
file, either cause deletion of the original element or do not perform the copy.<br />
The program calling this function must specify the name, version, and subtype to be<br />
given to the new element.<br />
7.3.1. Parameters<br />
The COPY_RAF_SYM_ELT function has the following parameters, each of which is<br />
described in the following subsections:<br />
• Function Packet<br />
• Source File Identifier<br />
• Destination File Identifier<br />
• Work Area<br />
7830 9796–013 7–17
Copying Program File Elements<br />
7.3.2. Function Packet<br />
The structure of the COPY_RAF_SYM_ELT function packet is defined in element<br />
FP$CPYRAFSYM. See Figure 7–4.<br />
0<br />
GENERIC PART<br />
1 DEST_ELT_NAME<br />
2<br />
3<br />
4 DEST_ELT_VERSION<br />
5<br />
6 INIT_DEST_FILE DEST_SYM_SUBTYPE<br />
7 a ON_CONFLICT<br />
8 AMOUNT_COPIED<br />
Figure 7–4. COPY_RAF_SYM_ELT Function Packet Items<br />
Item Descriptions<br />
DEST_ELT_NAME<br />
Indicates the name of the symbolic element PCFP creates. A null value is not<br />
allowed for this item.<br />
Data Type: characters (12)<br />
DEST_ELT_VERSION<br />
Indicates the version of the symbolic element PCFP creates. A value of spaces<br />
indicates an element with no version. A null value is not allowed for this item.<br />
Data Type: characters (12)<br />
INIT_DEST_FILE<br />
Indicates how PCFP should initialize an empty destination file.<br />
Data Type: value-list<br />
NONE = 0<br />
This value must be specified if the destination file is not initially empty. If the<br />
destination file is empty, it will be initialized as a standard program file (PF).<br />
7–18 7830 9796–013
PF = 1<br />
LPF = 2<br />
Initialize the destination file as a standard program file (PF).<br />
Initialize the destination file as a large program file (LPF).<br />
STANDARD_LEPF = 3<br />
Copying Program File Elements<br />
Initialize the destination file as a standard capacity, large element program file<br />
(standard LEPF).<br />
LARGE_LEPF = 4<br />
Initialize the destination file as a large capacity, large element program file (large<br />
LEPF).<br />
For values other than NONE, the destination file must be empty. Files are empty<br />
when initially created with @ASG or @CAT and when erased with the PCFP<br />
ERS_RAF function or the FURPUR @ERS command.<br />
DEST_SYM_SUBTYPE<br />
Indicates the subtype of the element to be created.<br />
Data Type: value-list<br />
SYM = 0 FLT = 16 GSA = 32<br />
ELT = 1 PNC = 17 MSG = 33<br />
ASM = 2 TCL = 18 PRT = 34<br />
COB = 3 MSM = 19 RPG = 35<br />
FOR = 4 MSD = 20 ADA = 36<br />
ALG = 5 MAC = 21 PEER = 37<br />
MAP = 6 APT = 22 C = 38<br />
DOC = 7 PGA = 23 FHLL = 39<br />
SEC = 8 QLP = 24 LINK = 40<br />
SSG = 9 INL = 25 COM = 41<br />
APL = 10 DCL = 26 PADS = 42<br />
BAS = 11 SDL = 27 SSDP = 43<br />
LSP = 12 FDP = 28 FLDP = 44<br />
PLS = 13 PSP = 29 ASMP = 64<br />
PL1 = 14 PAS = 30 COBP = 65<br />
CTS = 15 IPF = 31 FORP = 66<br />
7830 9796–013 7–19
Copying Program File Elements<br />
a = EXCLUSIVE_ASSIGN<br />
Indicates whether or not PCFP must assign the destination file exclusively.<br />
Data Type: condition<br />
ON_CONFLICT<br />
Indicates what action PCFP takes if the symbolic element resulting from the copy<br />
has the same name and version as a symbolic element already in the destination file.<br />
Data Type: value-list<br />
DO_NOT_COPY = 0<br />
Indicates that PCFP does create the new element.<br />
DELETE_ORIGINAL = 1<br />
Indicates that PCFP deletes the existing element with same name, version, and<br />
type, and creates the new element.<br />
AMOUNT_COPIED<br />
Indicates the size in words of the symbolic element this function created.<br />
Data Type: unsigned integer, returned<br />
7.3.3. Source File Identifier<br />
The source file identifier parameter names the file from which PCFP copies the element<br />
text. It must be a sector-addressable mass storage file for which the calling program has<br />
read privileges. The contents of the file must be SDF text. See 2.3 for a full description<br />
of this parameter.<br />
7.3.4. Destination File Identifier<br />
The destination file identifier parameter names the file in which PCFP creates the<br />
symbolic element. Initially, the named file must be either a program file or empty. It<br />
must reside on sector-addressable mass storage, and the calling program must have<br />
both read and write privileges for the file. See 2.3 for a description of this parameter.<br />
7.3.5. Work Area<br />
The COPY_RAF_SYM_ELT function works with any work area greater than or equal to<br />
the minimum size of 1,000 words. However, the function works more efficiently with<br />
larger work area sizes. The actual memory usable by the function varies with the size of<br />
the program file operated on, and the size of the element text copied. This function can<br />
make effective use of about (200 + 10*N +S) words, where N is the number of<br />
elements (deleted and undeleted) in the program file, and S is the word size of the<br />
7–20 7830 9796–013
Copying Program File Elements<br />
element text copied. For most situations, the minimum size work area gives acceptable<br />
performance.<br />
7.4. Copy Omnibus Element to RAF<br />
(COPY_OMN_ELT_RAF)<br />
The COPY_OMN_ELT_RAF function copies an omnibus element from a program file to a<br />
mass storage random-access file. It also returns the amount of text copied.<br />
The COPY_OMN_ELT_RAF function requires the destination file to be empty initially<br />
(that is, have no mass storage allocated to it), or it copies over anything already in the<br />
destination file.<br />
7.4.1. Parameters<br />
The COPY_OMN_ELT_RAF function has the following parameters, each of which is<br />
described in the following subsections:<br />
• Function Packet<br />
• Source File Identifier<br />
• Destination File Identifier<br />
• Work Area<br />
7.4.2. Function Packet<br />
This structure of the COPY_OMN_ELT_RAF function packet is defined in element<br />
FP$CPYOMNRAF. See Figure 7–5.<br />
0<br />
GENERIC PART<br />
1 ELT_NAME<br />
2<br />
3<br />
4 ELT_VERSION<br />
5<br />
6 b<br />
7 AMOUNT_COPIED<br />
Figure 7–5. COPY_OMN_ELT_RAF Function Packet Items<br />
7830 9796–013 7–21
Copying Program File Elements<br />
Item Descriptions<br />
ELT_NAME<br />
Indicates the name of the omnibus element PCFP copies. A null value is not allowed<br />
for this item.<br />
Data Type: characters (12)<br />
ELT_VERSION<br />
Indicates the version of the element PCFP copies. A value of spaces indicates an<br />
element with no version. A null value is not allowed for this item.<br />
Data Type: characters (12)<br />
b = PREVENT_OVERCOPY<br />
If TRUE, PCFP ensures that the destination file is empty before it copies any data<br />
into it. The run of the calling program must have read privileges for the destination<br />
file if this item is set to TRUE.<br />
Data Type: condition<br />
AMOUNT_COPIED<br />
Indicates the number of words of data PCFP copied to the destination file.<br />
Data Type: unsigned integer, returned<br />
7.4.3. Source File Identifier<br />
The source file identifier parameter names the file from which the element is copied.<br />
The named file must be a program file on sector-addressable mass storage for which the<br />
calling program has read privileges. See 2.3 for a description of this parameter.<br />
7.4.4. Destination File Identifier<br />
The destination file identifier parameter names the file to which the element text is<br />
copied. It must be a mass storage file (sector-addressable or word-addressable) for<br />
which the calling program has write privileges. See 2.3 for a full description of this<br />
parameter.<br />
7–22 7830 9796–013
7.4.5. Work Area<br />
Copying Program File Elements<br />
The COPY_OMN_ELT_RAF function works with any work area equal to or greater than<br />
the minimum size of 1,000 words. However, the function works more efficiently with<br />
larger work area sizes. The actual memory usable by the function varies with the size of<br />
the program file operated on and the size of the element text copied. This function can<br />
make effective use of about (200 + 10*N + S) words, where N is the number of<br />
elements (deleted and undeleted) in the program file, and S is the word size of the<br />
element text copied. For most situations, the minimum size work area gives acceptable<br />
performance.<br />
7.5. Copy RAF to Omnibus Element<br />
(COPY_RAF_OMN_ELT)<br />
The COPY_RAF_OMN_ELT function creates an omnibus element in a program file from<br />
the contents of a mass storage random-access file. The only restriction on the contents<br />
of the source file is that it may not contain any holes (unallocated areas).<br />
The following options are provided with this function:<br />
• Require PCFP to assign the destination file exclusively, or not.<br />
• Initialize an empty destination file as a PF, LPF, standard LEPF, or large LEPF.<br />
• If an omnibus element of the same name and version already exists in the program<br />
file, either cause deletion of the original element or do not complete the copy.<br />
7.5.1. Parameters<br />
The COPY_RAF_OMN_ELT function has the following parameters, each of which is<br />
described in the following subsections:<br />
• Function Packet<br />
• Source File Identifier<br />
• Destination File Identifier<br />
• Work Area<br />
7830 9796–013 7–23
Copying Program File Elements<br />
7.5.2. Function Packet<br />
The structure of the COPY_RAF_OMN_ELT function packet is defined in element<br />
FP$CPYRAFOMN. See Figure 7–6.<br />
0<br />
GENERIC PART<br />
1 DEST_ELT_NAME<br />
2<br />
3<br />
4 DEST_ELT_VERSION<br />
5<br />
6 INIT_DEST_FILE DEST_OMN_SUBTYPE<br />
7 a ON_CONFLICT<br />
8 AMOUNT_COPIED<br />
Figure 7–6. COPY_RAF_OMN_ELT Function Packet Items<br />
Item Descriptions<br />
DEST_ELT_NAME<br />
Indicates the name of the omnibus element PCFP creates. A null value is not<br />
allowed for this item.<br />
Data Type: characters (12)<br />
DEST_ELT_VERSION<br />
Indicates the version of the omnibus element PCFP creates. A null value is not<br />
allowed for this item. A value of spaces indicates an element with no version.<br />
Data Type: characters (12)<br />
INIT_DEST_FILE<br />
Indicates how PCFP should initialize an empty destination file.<br />
Data Type: value-list<br />
NONE = 0<br />
This value must be specified if the destination file is not initially empty. If the<br />
destination file is empty, it will be initialized as a standard program file (PF).<br />
7–24 7830 9796–013
PF = 1<br />
LPF = 2<br />
Initialize the destination file as a standard program file (PF).<br />
Initialize the destination file as a large program file (LPF).<br />
STANDARD_LEPF = 3<br />
Copying Program File Elements<br />
Initialize the destination file as a standard capacity, large element program file<br />
(standard LEPF).<br />
LARGE_LEPF = 4<br />
Initialize the destination file as a large capacity, large element program file (large<br />
LEPF).<br />
For values other than NONE, the destination file must be empty. Files are empty<br />
when initially created with @ASG or @CAT and when erased with the PCFP<br />
ERS_RAF function or the FURPUR @ERS command.<br />
DEST_OMN_SUBTYPE<br />
Indicates the subtype of the omnibus element PCFP creates.<br />
Data Type: value-list<br />
SYM = 0 FLT = 16 GSA = 32<br />
ELT = 1 PNC = 17 MSG = 33<br />
ASM = 2 TCL = 18 PRT = 34<br />
COB = 3 MSM = 19 RPG = 35<br />
FOR = 4 MSD = 20 ADA = 36<br />
ALG = 5 MAC = 21 PEER = 37<br />
MAP = 6 APT = 22 C = 38<br />
DOC = 7 PGA = 23 FHLL = 39<br />
SEC = 8 QLP = 24 LINK = 40<br />
SSG = 9 INL = 25 COM = 41<br />
APL = 10 DCL = 26 PADS = 42<br />
BAS = 11 SDL = 27 SSDP = 43<br />
LSP = 12 FDP = 28 FLDP = 44<br />
PLS = 13 PSP = 29<br />
PL1 = 14 PAS = 30<br />
CTS = 15 IPF = 31<br />
7830 9796–013 7–25
Copying Program File Elements<br />
a = EXCLUSIVE_ASSIGN<br />
Indicates whether or not PCFP must assign the destination file exclusively.<br />
Data Type: condition<br />
ON_CONFLICT<br />
Indicates what action PCFP takes if the omnibus element that results from the copy<br />
has the same name and version as an omnibus element already in the destination<br />
file.<br />
Data Type: value-list<br />
DO_NOT_COPY = 0<br />
Indicates that PCFP does not create the new element.<br />
DELETE_ORIGINAL = 1<br />
Indicates that PCFP deletes the existing element with the same name, version,<br />
and type, and creates the new element.<br />
AMOUNT_COPIED<br />
Indicates the size in words of the element this function created.<br />
Data Type: unsigned integer, returned<br />
7.5.3. Source File Identifier<br />
The source file identifier parameter names the file from which PCFP copies the element<br />
text. It must be a mass storage file (sector-addressable or word-addressable) for which<br />
the calling program has read privileges. The text of this file must not contain any holes<br />
(unallocated areas of mass storage). See 2.3 for a full description of this parameter.<br />
7.5.4. Destination File Identifier<br />
The destination file identifier parameter names the file in which PCFP creates the<br />
omnibus element. The named file must initially be either a program file or empty. It<br />
must reside on sector-addressable mass storage, and the calling program must have<br />
both read and write privileges for the file. See 2.3 for a description of this parameter.<br />
7.5.5. Work Area<br />
The COPY_RAF_OMN_ELT function works with any work area equal to or greater than<br />
the minimum size of 1,000 words. However, the function works more efficiently with<br />
larger work area sizes. The actual memory usable by the function varies with the size of<br />
the program file operated on, and the size of the element text copied. This function can<br />
make effective use of about (200 + 10*N + S) words, where N is the number of<br />
elements (deleted and undeleted) in the program file, and S is the word size of the<br />
7–26 7830 9796–013
Copying Program File Elements<br />
element text copied. For most situations, the minimum size work area gives acceptable<br />
performance.<br />
7830 9796–013 7–27
Copying Program File Elements<br />
7–28 7830 9796–013
Section 8<br />
Updating Program Files<br />
This section describes the following functions that update program files. These<br />
functions are in addition to those in Section 7, which update a program file by copying<br />
elements.<br />
• Change Element Attributes (CHG_ELT)<br />
• Delete Elements (DELETE_ELT)<br />
• Undelete Elements (UNDELETE_ELT)<br />
• Pack Program File (PACK_PF)<br />
• Create Program File Entry Point Table (PREP_PF)<br />
8.1. Change Element Attributes (CHG_ELT)<br />
The CHG_ELT function changes the attributes of one or more elements in a program file.<br />
The elements with attributes that are to be changed can be selected based on their<br />
name, version, type, subtype, or some combination of these. A partial name and version<br />
can be specified, as described in 2.6. Only undeleted elements can be selected.<br />
The following attributes can be changed using this function. The attributes that can be<br />
changed include all attributes that can be changed with the FURPUR @CHG and<br />
@CYCLE commands, as they apply to elements.<br />
• Element name<br />
• Element version<br />
The new name and/or version specified by the calling program may include wild-card<br />
characters, indicating that the corresponding characters from the original name or<br />
version are to be retained. See 2.6 for details on this.<br />
• Element subtype (applies to symbolic and omnibus elements only)<br />
• Maximum number of symbolic cycles retained<br />
If this change causes the maximum to become smaller than the number of cycles<br />
currently retained, PCFP recopies the text of the element so that only images within<br />
the new cycle limit are retained.<br />
• Date and time the element was created<br />
7830 9796–013 8–1
Updating Program Files<br />
The CHG_ELT function has the following options:<br />
• If CHG_ELT would cause a duplicate element (same name, version, and type) to be<br />
created, PCFP takes one of the following two actions:<br />
− Marks the existing element as deleted and proceeds with the change<br />
− Leaves the element unchanged<br />
• Requires PCFP to assign the program file exclusively<br />
• Returns name, version, type, subtype, and result indicator for<br />
− Each element that was selected and successfully changed<br />
− Each element that was selected but could not be changed<br />
− Each element that was selected, whether it was changed or not<br />
− No elements<br />
The result indicator returned for each element indicates whether or not the change<br />
could be completed for that element, and any error or warning associated with<br />
changing the attributes of that element.<br />
In all cases, this function returns the number of elements it selected for change, the<br />
number it successfully changed, and the number that it could not change.<br />
When this function causes one or more relocatable elements to be deleted from the<br />
program file (due to name-version-type conflict with a renamed element), it removes any<br />
relocatable entry point table that previously existed in the program file. However, when<br />
this function causes similar deletion of an object module, it does not remove the object<br />
module entry point table.<br />
When this function causes one or more procedure symbolic elements to be deleted from<br />
the program file, it also deletes any procedure entries associated with those elements.<br />
8.1.1. Parameters<br />
The CHG_ELT function has the following parameters, each of which is described in the<br />
following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Return Entry<br />
• Work Area<br />
8–2 7830 9796–013
8.1.2. Function Packet<br />
0<br />
1<br />
2<br />
3<br />
4<br />
5<br />
10<br />
11<br />
12<br />
13<br />
14<br />
15<br />
6 a b c d<br />
Updating Program Files<br />
The structure of the CHG_ELT function packet is defined in element FP$CHGELT. See<br />
Figure 8–1.<br />
GENERIC PART<br />
RETURN-INFORMATION PART<br />
ELT_NAME<br />
ELT_VERSION<br />
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 e<br />
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 e<br />
9 f f f f f f f f f f f f f f f f f f<br />
NEW_ELT_NAME<br />
NEW_ELT_VERSION<br />
16 g h i j NEW_OMN_SYM_SUBTYPE<br />
17 NEW_CYCLE_LIMIT<br />
18 INFO_TO_RETURN INFO_DETAIL<br />
19 NUM_SELECTED<br />
20 NUM_SUCCESSFUL<br />
21 NUM_FAILED<br />
Item Descriptions<br />
ELT_NAME<br />
Figure 8–1. CHG_ELT Function Packet Items<br />
7830 9796–013 8–3
Updating Program Files<br />
Indicates the name or pattern of the name of the elements that PCFP changes. The<br />
value the calling program supplies for this item may contain the question mark ( ? )<br />
and the asterisk ( * ) wild-card characters as described in 2.6. A null value indicates<br />
that the elements are selected for change without regard to their names.<br />
Data Type: characters (12)<br />
ELT_VERSION<br />
Indicates the version or pattern of the version of the elements that PCFP changes.<br />
The value that the calling program supplies for this item may contain the question<br />
mark ( ? ) and the asterisk ( * ) wild-card characters as described in 2.6. A null value<br />
indicates that the elements are selected for change without regard to their versions.<br />
Data Type: characters (12)<br />
a = ABS_TYPE<br />
Indicates whether PCFP changes absolute elements.<br />
Data Type: condition<br />
b = OMN_TYPE<br />
Indicates whether PCFP changes omnibus elements.<br />
Data Type: condition<br />
c = REL_TYPE<br />
Indicates whether PCFP changes relocatable elements.<br />
Data Type: condition<br />
d = SYM_TYPE<br />
Indicates whether PCFP changes symbolic elements.<br />
Data Type: condition<br />
8–4 7830 9796–013
Updating Program Files<br />
If the calling program sets items ABS_TYPE, OMN_TYPE, REL_TYPE, and SYM_TYPE to<br />
all FALSE or all TRUE, PCFP selects elements to be changed regardless of their types.<br />
e = OMN_SYM_SUBTYPE array (0:71)<br />
Indicates which subtypes of omnibus and symbolic elements PCFP changes. Each<br />
item in this array occupies a single bit. If the calling program sets any entries in this<br />
array to TRUE (1), only omnibus and symbolic elements that have a numeric subtype<br />
corresponding to a TRUE entry are changed. If the calling program sets no item in<br />
the array to TRUE, omnibus and symbolic elements are changed regardless of<br />
subtype. This item applies only to symbolic and omnibus elements; it does not<br />
affect the selection of elements of other types.<br />
Data Type: condition array<br />
f = ABS_SUBTYPE array (0:17)<br />
Indicates which subtypes of absolute elements PCFP changes. Each item in this<br />
array occupies a single bit. If the calling program sets any entries in this array to<br />
TRUE (1), only absolute elements that have a numeric subtype corresponding to a<br />
TRUE entry are changed. If the calling program sets no item in the array to TRUE,<br />
absolute elements are changed regardless of subtype. This item applies only to<br />
absolute elements; it does not affect the selection of elements of other types.<br />
Data Type: condition array<br />
NEW_ELT_NAME<br />
Indicates the new name for the element. The value the calling program supplies for<br />
this item may contain the question mark ( ? ) wild-card character. PCFP replaces<br />
each question mark with the corresponding character in the original element name.<br />
If this value is null, PCFP does not change the names of the elements selected.<br />
Data Type: characters (12)<br />
NEW_ELT_VERSION<br />
Indicates the new version for the element. The value the calling program supplies<br />
for this item may contain the question mark ( ? ) wild-card character. PCFP replaces<br />
each question mark with the corresponding character in the original element version.<br />
If the value PCFP supplies for this item is all spaces, the new version name is made<br />
all spaces. If this value is null, PCFP does not change the versions of the elements<br />
selected.<br />
Data Type: characters (12)<br />
7830 9796–013 8–5
Updating Program Files<br />
g = CHG_OMN_SYM_SUBTYPE<br />
Indicates whether PCFP changes the subtype of the omnibus and symbolic<br />
elements it selects. When the calling program sets this item to TRUE, it must also<br />
set the new subtype in NEW_OMN_SYM_SUBTYPE.<br />
Data Type: condition<br />
h = CHG_DATE_TIME<br />
Indicates whether PCFP changes the dates and times of the elements it selects.<br />
Setting CHANGE_DATE_TIME = FALSE indicates they are not changed. Setting<br />
CHANGE_DATE_TIME = TRUE indicates they are changed to the date and time<br />
when PCFP performs the operation.<br />
Data Type: condition<br />
i = EXCLUSIVE_ASSIGN<br />
Indicates whether or not PCFP must assign the program file exclusively prior to<br />
performing the operation.<br />
Data Type: condition<br />
j = PROCEED_ON_CONFLICT<br />
Indicates the action PCFP takes if an element is being given a new name and version<br />
that would cause it to have the same name, version, and type as an existing<br />
element. FALSE indicates that PCFP does not perform the change for that element,<br />
and TRUE indicates that PCFP performs the change for that element after deleting<br />
the existing element with the same name, version, and type.<br />
Data Type: condition<br />
8–6 7830 9796–013
NEW_OMN_SYM_SUBTYPE<br />
Updating Program Files<br />
Indicates the new subtype PCFP gives to the symbolic and omnibus elements it<br />
selects. The calling program can set this item to a nonzero value only if it also sets<br />
CHANGE_OMN_SYM_SUBTYPE = TRUE.<br />
Data Type: value-list<br />
SYM = 0 FLT = 16 GSA = 32<br />
ELT = 1 PNC = 17 MSG = 33<br />
ASM = 2 TCL = 18 PRT = 34<br />
COB = 3 MSM = 19 RPG = 35<br />
FOR = 4 MSD = 20 ADA = 36<br />
ALG = 5 MAC = 21 PEER = 37<br />
MAP = 6 APT = 22 C = 38<br />
DOC = 7 PGA = 23 FHLL = 39<br />
SEC = 8 QLP = 24 LINK = 40<br />
SSG = 9 INL = 25 COM = 41<br />
APL = 10 DCL = 26 PADS = 42<br />
BAS = 11 SDL = 27 SSDP = 43<br />
LSP = 12 FDP = 28 FLDP = 44<br />
PLS = 13 PSP = 29 ASMP = 64<br />
PL1 = 14 PAS = 30 COBP = 65<br />
CTS =15 IPF = 31 FORP = 66<br />
The values ASMP, COBP, and FORP are not valid for omnibus elements. If the<br />
calling program attempts to give an omnibus element one of these subtypes, PCFP<br />
does not change that element.<br />
NEW_CYCLE_LIMIT<br />
Indicates the new symbolic cycle limit that PCFP gives to the symbolic elements that<br />
it selects. For any element selected where this value is less than the number of<br />
cycles currently retained, PCFP recopies the element text so that the number of<br />
cycles actually retained is reduced to satisfy the new maximum. When the calling<br />
program sets this item to zero, PCFP does not change the cycle limit for any<br />
element.<br />
Data Type: unsigned integer range (0 to 63)<br />
7830 9796–013 8–7
Updating Program Files<br />
INFO_TO_RETURN<br />
Indicates which of the elements PCFP selected have individual information returned<br />
to the calling program.<br />
Data Type: value-list<br />
NONE = 0<br />
Indicates that PCFP returns individual information for no elements.<br />
ERROR_ONLY = 1<br />
Indicates that PCFP returns individual information only for each element that it<br />
selected but was not able to change.<br />
NONERROR_ONLY = 2<br />
Indicates that PCFP returns individual information only for each element that it<br />
selected and actually changed.<br />
ALL_INFO = 3<br />
INFO_DETAIL<br />
Indicates that PCFP returns individual information for each element it selected,<br />
whether or not the element was successfully changed.<br />
For each individual element for which information is returned, indicates what parts of<br />
the element information PCFP returns. This item is ignored if the calling program set<br />
INFO_TO_RETURN = NONE.<br />
Data Type: value-list<br />
SHORT = 0<br />
Indicates that for each element that has return information, PCFP returns only<br />
the following items: RESULT_INDICATOR, ELT_NAME, ELT_VERSION,<br />
ELT_TYPE, ELT_SUBTYPE, SEQ_NUM.<br />
LONG = 1<br />
Indicates that PCFP returns all of the element information described in 6.2.4 for<br />
each element.<br />
NUM_SELECTED<br />
Indicates how many elements PCFP selected, whether they were changed<br />
successfully or not.<br />
Data Type: unsigned integer, returned<br />
8–8 7830 9796–013
NUM_SUCCESSFUL<br />
Updating Program Files<br />
Indicates how many of the elements PCFP selected were actually changed.<br />
Data Type: unsigned integer, returned<br />
NUM_FAILED<br />
Indicates how many of the elements PCFP selected were not changed. The reason<br />
for each failure is indicated by RESULT_INDICATOR in the return entry, if the calling<br />
program requested this information to be returned. In all cases, NUM_SELECTED =<br />
NUM_SUCCESSFUL + NUM_FAILED.<br />
Data Type: unsigned integer, returned<br />
8.1.3. File Identifier<br />
The file identifier parameter names the file in which elements are to be changed. The<br />
named file must be a program file on sector-addressable mass storage for which the<br />
calling program has both read and write privileges. See 2.3 for a full description of this<br />
parameter.<br />
8.1.4. Return Entry<br />
PCFP returns one entry for each element it selected, subject to the constraints indicated<br />
by INFO_TO_RETURN in the function packet. See 6.2.4 for a description of these<br />
entries.<br />
For those elements that PCFP selected but was not able to change, PCFP sets the item<br />
RESULT_INDICATOR in the return entry to a value other than FP_ERR_NONE (0) to<br />
indicate the error and its cause. For the CHG_ELT function, RESULT_INDICATOR can<br />
have the following values for elements that PCFP was not able to change:<br />
FP_WARN_ELT_CONFLICT<br />
Indicates that PCFP was not able to change the element because the program file<br />
already contains an element with the same type that has a name and version<br />
matching the new name and version given to this element. This value can be<br />
returned only if the calling program set PROCEED_ON_CONFLICT = FALSE in the<br />
function packet.<br />
FP_WARN_BAD_ELT_NAME<br />
Indicates that PCFP was unable to change the element because the new name<br />
generated for the element contains an embedded space.<br />
FP_WARN_BAD_ELT_VERSION<br />
Indicates that PCFP was unable to change the element because the new version<br />
generated for the elements contain an embedded space.<br />
7830 9796–013 8–9
Updating Program Files<br />
FP_WARN_BAD_SUBTYPE<br />
8.1.5. Work Area<br />
Indicates that PCFP was unable to change the element because the new subtype<br />
specified is not legal for an omnibus element.<br />
The CHG_ELT function can always operate with any work area equal to or greater than<br />
the minimum size of 1,000 words. However, this function can work more efficiently<br />
with a larger work area. The actual memory usable by this function varies with the size<br />
of the program file on which it operates. This function can make effective use of about<br />
(350 + 10*N) words, where N is the number of elements (deleted and undeleted) in the<br />
program file. Thus, a work area size larger than the minimum can be useful with a<br />
program file with more than 65 elements. The maximum size work area of 20,000<br />
words is useful for program files containing 2,000 elements or more.<br />
8.2. Delete Elements (DELETE_ELT)<br />
The DELETE_ELT function deletes one or more elements from a program file. It<br />
provides the capability of the FURPUR @DELETE command as it applies to elements. It<br />
also provides some of the capabilities provided by the FURPUR @PACK command.<br />
The elements to be deleted can be selected based upon name, version, type, subtype,<br />
or some combination of these. A partial name and version can be specified, as<br />
described in 2.6. Only undeleted elements can be selected.<br />
The DELETE_ELT function provides the following options:<br />
• Returns name, version, type, and subtype of each element that is deleted<br />
• Requires PCFP to assign the program file exclusively<br />
In all cases, this function returns the number of elements successfully deleted.<br />
When this function deletes one or more relocatable elements from the program file, it<br />
removes any relocatable entry point table that previously existed in the program file.<br />
However, when this function deletes an object module absolute element from the<br />
program file, it does not remove any existing object module entry point table.<br />
When this function deletes one or more procedure symbolic elements from the program<br />
file, it also deletes any procedure entries associated with those elements.<br />
8–10 7830 9796–013
8.2.1. Parameters<br />
Updating Program Files<br />
The DELETE_ELT function has the following parameters, each of which is described in<br />
the following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Return Entry<br />
• Work Area<br />
8.2.2. Function Packet<br />
0<br />
1<br />
2<br />
3<br />
4<br />
5<br />
6 a b c d<br />
This structure of the DELETE_ELT function packet is defined in element FP$DELELT.<br />
See Figure 8–2.<br />
GENERIC PART<br />
RETURN-INFORMATION PART<br />
ELT_NAME<br />
ELT_VERSION<br />
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 e<br />
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 e<br />
9 f f f f f f f f f f f f f f f f f f INFO_TO_RETURN<br />
10 g INFO_DETAIL<br />
11 NUM_SELECTED<br />
Figure 8–2. DELETE_ELT Function Packet Items<br />
7830 9796–013 8–11
Updating Program Files<br />
Item Descriptions<br />
ELT_NAME<br />
Indicates the name or pattern of the name of the elements that PCFP deletes. The<br />
value the calling program supplies for this item may contain the question mark ( ? )<br />
and the asterisk ( * ) wild-card characters as described in 2.6. A null value indicates<br />
that the elements are deleted without regard to element name.<br />
Data Type: characters (12)<br />
ELT_VERSION<br />
Indicates the version or pattern of the version of the elements PCFP deletes. The<br />
value the calling program supplies for this item may contain the question mark ( ? )<br />
and the asterisk ( * ) wild-card characters as described in 2.6. A null value indicates<br />
that the elements are deleted without regard to version.<br />
Data Type: characters (12)<br />
a = ABS_TYPE<br />
Indicates whether PCFP deletes absolute elements.<br />
Data Type: condition<br />
b = OMN_TYPE<br />
Indicates whether PCFP deletes omnibus elements.<br />
Data Type: condition<br />
c = REL_TYPE<br />
Indicates whether PCFP deletes relocatable elements.<br />
Data Type: condition<br />
d = SYM_TYPE<br />
Indicates whether PCFP deletes symbolic elements.<br />
Data Type: condition<br />
8–12 7830 9796–013
Updating Program Files<br />
If the calling program sets items ABS_TYPE, OMN_TYPE, REL_TYPE, and SYM_TYPE all<br />
to FALSE or all to TRUE, PCFP deletes elements regardless of their types.<br />
e = OMN_SYM_SUBTYPE array (0:71)<br />
Indicates which subtypes of omnibus and symbolic elements PCFP deletes. Each<br />
item in this array occupies a single bit. If the calling program sets any entries in this<br />
array to TRUE (1), only omnibus and symbolic elements that have a numeric subtype<br />
corresponding to a TRUE entry are deleted. If the calling program sets no item in the<br />
array to TRUE, omnibus and symbolic elements are selected regardless of subtype.<br />
This item applies only to symbolic and omnibus elements; it does not affect the<br />
selection of elements of other types.<br />
Data Type: condition array<br />
f = ABS_SUBTYPE array (0:17)<br />
Indicates which subtypes of absolute elements PCFP deletes. Each item in this<br />
array occupies a single bit. If the calling program sets any entries in this array to<br />
TRUE (1), only absolute elements that have a numeric subtype corresponding to a<br />
TRUE entry are deleted. If the calling program sets no item in the array to TRUE,<br />
absolute elements are deleted regardless of subtype. This item applies only to<br />
absolute elements; it does not affect the selection of elements of other types.<br />
Data Type: condition array<br />
INFO_TO_RETURN<br />
Indicates whether PCFP returns information about the individual elements it deleted<br />
to the calling program.<br />
Data Type: value-list<br />
NONE = 0<br />
Indicates that PCFP does not return individual information about each element<br />
deleted.<br />
ALL_INFO = 3<br />
Indicates that PCFP returns individual information about each element deleted.<br />
g = EXCLUSIVE_ASSIGN<br />
Indicates whether or not PCFP must assign the program file exclusively prior to<br />
performing the operation.<br />
Data Type: condition<br />
7830 9796–013 8–13
Updating Program Files<br />
INFO_DETAIL<br />
For each individual element for which information is returned, indicates what parts of<br />
the element information PCFP returns. This item is ignored if the calling program set<br />
INFO_TO_RETURN = NONE.<br />
Data Type: value-list<br />
SHORT = 0<br />
Indicates that only the following items will be returned: RESULT_INDICATOR,<br />
ELT_NAME, ELT_VERSION, ELT_TYPE, ELT_SUBTYPE, and ELT_SEQ_NUM.<br />
LONG = 1<br />
Indicates that all of the element information described in 6.2.4 is returned.<br />
NUM_SELECTED<br />
Indicates how many elements PCFP deleted.<br />
Data Type: unsigned integer, returned<br />
8.2.3. File Identifier<br />
The file identifier parameter names the file in which elements are to be deleted. The<br />
named file must be a program file on sector-addressable mass storage for which the<br />
calling program has both read and write privileges. See 2.3 for a full description of this<br />
parameter.<br />
8.2.4. Return Entry<br />
PCFP returns an entry for each element it deleted, subject to the constraints indicated by<br />
INFO_TO_RETURN in the function packet. See 6.2.4 for a description of these entries.<br />
For the DELETE_ELT function, items that PCFP selects for deletion can always be<br />
deleted successfully. Therefore, the item RESULT_INDICATOR in the return entry<br />
always has the value FP_ERR_NONE(0).<br />
8.2.5. Work Area<br />
The DELETE_ELT function can always operate with any work area that is equal to or<br />
greater than the minimum size of 1,000 words. However, this function can work more<br />
efficiently with a larger work area. The actual memory usable by this function varies with<br />
the size of the program file on which it operates. This function can make effective use<br />
of about (350 + 10*N) words, where N is the number of elements (deleted and<br />
undeleted) in the program file. Thus, a work area size larger than the minimum is useful<br />
with a program file with more than 65 elements. The maximum size work area of<br />
20,000 words is useful for program files containing 2,000 elements or more.<br />
8–14 7830 9796–013
8.3. Undelete Elements (UNDELETE_ELT)<br />
Updating Program Files<br />
The UNDELETE_ELT function undeletes one or more elements from a program file.<br />
All elements with the same element name, version name, and type make up an<br />
element/version/type set. At most, one of the elements in the set may be undeleted.<br />
The rest of the elements in the set are deleted. The UNDELETE_ELT function allows<br />
selection and undeletion of any deleted member of the element/version/type set. If the<br />
set contains an undeleted element before the function is called, that element is changed<br />
to deleted.<br />
Note that once the PACK_PF function is called (see 8.4), all deleted members of all<br />
element/version/type sets are permanently removed and are no longer available to be<br />
undeleted.<br />
The elements to be undeleted can be selected based on name, version, type, subtype,<br />
sequence number, or some combination of these. A partial name and version can be<br />
specified, as described in 2.6. Only deleted elements can be selected.<br />
Table 8–1 illustrates the concept of absolute and relative element sequence numbers<br />
that is unique to the UNDELETE_ELT function. The columns represent a set of five<br />
elements that have the same element name, version name, and type. In this example,<br />
the element with the highest sequence number is undeleted and the other four<br />
elements are deleted. This is the normal case for program files. The rows identify how<br />
the individual members of the set are identified by absolute sequence number and by<br />
relative sequence number. The element with the highest absolute sequence number in<br />
the element/version/type set always has relative sequence number 0. The<br />
UNDELETE_ELT function can be used to change which member of the<br />
element/version/type set is undeleted (No in the Deleted row), but the relative sequence<br />
numbers of the set remain unchanged. Using Table 8–1 as an example, if<br />
UNDELETE_ELT changes absolute sequence number 62 to undeleted and absolute<br />
sequence number 112 to deleted, these two elements are still identified as relative<br />
sequence numbers -2 and 0, respectively.<br />
Table 8–1. Absolute and Relative Sequence Numbers<br />
(sample)<br />
Attributes Element/Version/Type Set Members<br />
Deleted Yes Yes Yes Yes No<br />
Absolute<br />
Sequence<br />
Number<br />
Relative<br />
Sequence<br />
Number<br />
13<br />
-4<br />
48<br />
-3<br />
7830 9796–013 8–15<br />
62<br />
-2<br />
78<br />
-1<br />
112<br />
0
Updating Program Files<br />
The UNDELETE_ELT function provides the following options:<br />
• Requires PCFP to assign the file exclusively or not.<br />
• If UNDELETE_ELT would cause an undeleted element with the same name, version,<br />
and type to be deleted, do one of the following:<br />
− Delete the element and proceed with the undelete<br />
− Do not delete the element and do not proceed with the undelete<br />
• Sequence number is used to select elements to be undeleted by one of the<br />
following methods (as illustrated in Table 8–1):<br />
− A relative sequence number identifies a member of each element/version/type<br />
set to be undeleted.<br />
− An absolute sequence number identifies one program file element to be<br />
undeleted.<br />
• Returns name, version, type, subtype, and result indicator for<br />
− Each element that was selected and successfully undeleted<br />
− Each element that was selected, but not undeleted<br />
− Each element that was selected, whether it was undeleted or not<br />
− No elements<br />
In all cases, the UNDELETE_ELT function returns the number of elements it selected,<br />
the number it successfully undeleted, and the number it did not undelete.<br />
When this function undeletes one or more relocatable elements, it removes any<br />
relocatable entry point table that previously existed in the program file. However, when<br />
this function undeletes one or more object module absolute elements in the program<br />
file, it does not remove any existing object module entry point tables.<br />
When the function undeletes one or more procedure symbolic elements, it also<br />
undeletes all procedure table entries associated with those elements. When the<br />
function deletes one or more procedure symbolic elements, it also deletes all procedure<br />
table entries associated with those elements.<br />
8.3.1. Parameters<br />
The UNDELETE_ELT function has the following parameters, each of which is described<br />
in the following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Return Entry<br />
• Work Area<br />
8–16 7830 9796–013
8.3.2. Function Packet<br />
0<br />
1<br />
2<br />
3<br />
4<br />
5<br />
6 a b c d<br />
The structure of the UNDELETE_ELT function packet is defined in element<br />
FP$UNDELELT. See Figure 8–3.<br />
GENERIC PART<br />
RETURN-INFORMATION PART<br />
ELT_NAME<br />
ELT_VERSION<br />
Updating Program Files<br />
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 e<br />
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 e<br />
9 f f f f f f f f f f f f f f f f f f SEQ_NUM_TYPE<br />
10 g h SEQ_NUM<br />
11 INFO_TO_RETURN INFO_DETAIL<br />
12 NUM_SELECTED<br />
13 NUM_SUCCESSFUL<br />
14 NUM_FAILED<br />
Figure 8–3. UNDELETE_ELT Function Packet Items<br />
Item Descriptions<br />
ELT_NAME<br />
Indicates the name or pattern of the name of the elements that this function<br />
undeletes. The value the calling program supplies for this item may contain the<br />
question mark ( ? ) and the asterisk ( * ) wild-card characters as described in 2.6. A<br />
null value indicates the elements are undeleted without regard to element name.<br />
Data Type: characters (12)<br />
7830 9796–013 8–17
Updating Program Files<br />
ELT_VERSION<br />
Indicates the version or pattern of the version of the elements that this function<br />
undeletes. The value the calling program supplies for this item may contain the<br />
question mark ( ? ) and the asterisk ( * ) wild-card characters as described in 2.6. A<br />
null value indicates the elements are undeleted without regard to version.<br />
Data Type: characters (12)<br />
a = ABS_TYPE<br />
Indicates whether absolute elements are undeleted.<br />
Data Type: condition<br />
b = OMN_TYPE<br />
Indicates whether omnibus elements are undeleted.<br />
Data Type: condition<br />
c = REL_TYPE<br />
Indicates whether relocatable elements are undeleted.<br />
Data Type: condition<br />
d = SYM_TYPE<br />
Indicates whether symbolic elements are undeleted.<br />
Data Type: condition<br />
If the calling program sets items ABS_TYPE, OMN_TYPE, REL_TYPE and SYM_TYPE all<br />
to FALSE or all to TRUE, elements are undeleted without regard to their type.<br />
e = OMN_SYM_SUBTYPE array (0:71)<br />
Indicates which subtypes of omnibus and symbolic elements are undeleted. Each<br />
item in this array occupies a single bit. If the calling program sets any entries in this<br />
array to TRUE (1), only omnibus and symbolic elements that have a numeric subtype<br />
corresponding to the TRUE entry are undeleted. If the calling program sets no item<br />
in the array to TRUE, omnibus and symbolic elements are undeleted without regard<br />
to their subtype. This item applies only to omnibus and symbolic elements and does<br />
not affect the selection of elements of other types.<br />
Note that the CHG_ELT, COPY_ELT, COPY_RAF_OMN_ELT and<br />
COPY_RAF_SYM_ELT functions can be used to create element/version/type sets<br />
where the set members have different subtypes. An element/version/type set will<br />
not be selected for undeletion unless all of its members match subtype<br />
specifications.<br />
8–18 7830 9796–013
Data Type: condition array<br />
f = ABS_SUBTYPE array (0:17)<br />
Updating Program Files<br />
Indicates which subtypes of absolute elements are undeleted. Each item in this<br />
array occupies a single bit. If the calling program sets any entries in this array to<br />
TRUE (1), only absolute elements that have a numeric subtype corresponding to the<br />
TRUE entry are undeleted. If the calling program sets no item in the array to TRUE,<br />
absolute elements are undeleted without regard to their subtype. This item applies<br />
only to absolute elements and does not affect the selection of elements of other<br />
types.<br />
Note that the COPY_ELT function can be used to create element/version/type sets<br />
where the set members have different subtypes. An element/version/type set will<br />
not be selected for undeletion unless all of its members match subtype<br />
specifications.<br />
Data Type: condition array<br />
SEQ_NUM_TYPE<br />
Indicates if SEQ_NUM contains a relative sequence number, identifying a member of<br />
each element/version/type set, or an absolute sequence number, identifying a single<br />
element in the program file.<br />
Data Type: value-list<br />
REL = 0<br />
Indicates that SEQ_NUM contains a relative sequence number that identifies a<br />
member of each element/version/type set to undelete.<br />
ABS = 1<br />
Indicates that SEQ_NUM contains an absolute sequence number that identifies<br />
a single element in the program file.<br />
g = EXCLUSIVE_ASSIGN<br />
Indicates whether or not the program file must be assigned exclusively.<br />
Data Type: condition<br />
h = ALLOW_DELETION<br />
Indicates what action to take if undeletion of an element would cause the deletion of<br />
another member of the element/version/type set. FALSE indicates that the<br />
undeleted element is not to be deleted, so the selected element is not undeleted.<br />
TRUE indicates that deletion is allowed. The undeleted element is deleted before<br />
the selected element is undeleted.<br />
Data Type: condition<br />
7830 9796–013 8–19
Updating Program Files<br />
SEQ_NUM<br />
Indicates the specific sequence number to undelete. No undeletion occurs if the<br />
indicated sequence number does not exist, if it is already undeleted, or if there is<br />
already an undeleted member of the element/version/type set and the<br />
ALLOW_DELETION item does not allow its deletion.<br />
If the calling program sets SEQ_NUM_TYPE = REL, it must set this item to a value<br />
between -26,145 and 0 inclusive.<br />
If the calling program sets SEQ_NUM_TYPE = ABS, it must set this item to a value<br />
between 1 and 26,146 inclusive. It must also set the ELT_NAME and ELT_VERSION<br />
items to null values and it must set the ABS_TYPE, OMN_TYPE, REL_TYP and<br />
SYM_TYPE items, the OMN_SYM_SUBTYPE condition array and the ABS_SUBTYPE<br />
condition array to FALSE.<br />
Data Type: signed integer range (-26,145 through 26,146)<br />
INFO_TO_RETURN<br />
Indicates which of the selected elements have individual information returned to the<br />
calling program.<br />
Data Type: value-list<br />
NONE = 0<br />
Indicates that individual information is returned for no elements.<br />
ERROR_ONLY = 1<br />
Indicates that individual information is returned only for elements that are<br />
selected but not undeleted.<br />
NONERROR_ONLY = 2<br />
Indicates that individual information is returned only for elements that are<br />
selected and successfully undeleted.<br />
ALL_INFO = 3<br />
INFO_DETAIL<br />
Indicates that individual information is returned for all elements that are selected,<br />
without regard to whether or not they are successfully undeleted.<br />
For each element for which information is returned, indicates what parts of the<br />
element information is returned. This item is ignored if the calling program sets<br />
INFO_TO_RETURN = NONE.<br />
Data Type: value-list<br />
8–20 7830 9796–013
SHORT = 0<br />
Updating Program Files<br />
Indicates that for each element for which information is returned, the element<br />
items RESULT_INDICATOR, ELT_NAME, ELT_VERSION, ELT_TYPE,<br />
ELT_SUBTYPE, and ELT_SEQ_NUM are returned.<br />
LONG = 1<br />
Indicates that for each element for which information is returned, all information<br />
described in 6.2.4 is returned.<br />
SUMMARY = 3<br />
Indicates that instead of returning individual information for each element, PCFP<br />
summarizes the information and returns it in a single summary entry, as<br />
described in 7.1.5.<br />
NUM_SELECTED<br />
Indicates the number of element/version/type sets that matched function packet<br />
specifications for element name, version, type and subtype.<br />
Data Type: unsigned integer, returned<br />
NUM_SUCCESSFUL<br />
Indicates the number of elements actually undeleted.<br />
Data Type: unsigned integer, returned<br />
NUM_FAILED<br />
Indicates the number of element/version/type sets selected for which no element<br />
was undeleted. No element was undeleted because the relative sequence number<br />
(SEQ_NUM) does not exist in the element/version/type set, because the relative<br />
sequence number is already undeleted or because a member of the<br />
element/version/type set is undeleted and the ALLOW_DELETION specification<br />
does not allow its deletion. If the calling program requested return of error<br />
information, the reason that the element was not undeleted is returned in the<br />
RESULT_INDICATOR return entry item.<br />
Serious errors that cause termination of the UNDELETE_ELT function are not<br />
counted in this item. These errors are reported in the generic part of the function<br />
packet, as described in 2.4.1.<br />
When the function completes, NUM_SELECTED is equal to the sum of<br />
NUM_SUCCESSFUL and NUM_FAILED. When the function terminates because of<br />
an error, NUM_SELECTED can be one greater than the sum of NUM_SUCCESSFUL<br />
and NUM_FAILED.<br />
Data Type: unsigned integer, returned<br />
7830 9796–013 8–21
Updating Program Files<br />
8.3.3. File Identifier<br />
The file identifier parameter names the file in which elements are to be undeleted. The<br />
named file must be a program file on sector-addressable mass storage for which the<br />
calling program has both read and write privileges. See 2.3 for a full description of this<br />
parameter.<br />
8.3.4. Return Entry<br />
When the function packet item INFO_DETAIL is set to SHORT or LONG, one entry is<br />
returned for each element indicated by the function packet item INFO_TO_RETURN.<br />
See 6.2.4 for a description of these entries.<br />
For elements that were successfully undeleted, the RESULT_INDICATOR item in the<br />
return entry is set to one of the following values:<br />
FP_ERR_NONE<br />
Indicates that the element was successfully undeleted.<br />
FP_INFO_PROC_TBL_ERR<br />
Indicates that the element was successfully undeleted, but that some or all of the<br />
procedure table entries associated with the element could not be processed. When<br />
this error is detected, the function is terminated.<br />
For elements that were selected but were not undeleted, the RESULT_INDICATOR item<br />
in the return entry is set to one of the following values:<br />
FP_WARN_ELT_REL_SEQ_NUM_ERR<br />
Indicates that for this element/version/type set the relative sequence number<br />
specified in the SEQ_NUM item does not exist. The return entry is the member of<br />
the element/version/types set with the lowest sequence number.<br />
FP_WARN_ELT_UNDELETED<br />
Indicates that the selected element was already undeleted.<br />
FP_WARN_ELT_DELETE_NOT_ALLOWED<br />
indicates that the selected element was not undeleted because another member of<br />
the element/version/type set was undeleted and the ALLOW_DELETION<br />
specification did not allow its deletion.<br />
When the function packet item INFO_DETAIL is set to SUMMARY, a single entry is<br />
returned summarizing the undelete function for elements indicated by the function<br />
packet item INFO_TO_RETURN. The item NUM_RTN_ENTRIES in the Return<br />
Information part of the function packet is set to 1. See 7.1.5 for a description of return<br />
entry.<br />
8–22 7830 9796–013
8.3.5. Work Area<br />
Updating Program Files<br />
The UNDELETE_ELT function can always operate with any work area greater than or<br />
equal to the minimum size of 2,000 words. In many situations this function works more<br />
efficiently with a larger work area size. The actual work area usable by this function<br />
varies with the size of the program file it operates on, the number of elements it<br />
undeletes, and options specified in the function packet.<br />
The formula below can be used to calculate the size of the work area usable by the<br />
function. All of the information needed in this calculation can be obtained using the<br />
ACQ_BASIC_PF_INFO function, described in 6.1.<br />
The usable size of the work area can be calculated by the formula (350 + 10*T + U + V +<br />
W), where:<br />
350 The fixed function requirement.<br />
T The number of elements in the file. This corresponds to the<br />
ACQ_BASIC_PF_INFO return value ELT_NUM_ENTRIES.<br />
U The size of a condition array that is required when either ELT_NAME or<br />
ELT_VERSION contain wild-card characters or null values. The size of the<br />
condition array is (T / 36).<br />
V The size of a condition array that is required when SEQ_NUM_TYPE has a value<br />
of REL (0). The size of the condition array is (T / 36).<br />
W The number of procedure elements to undelete or delete with the function,<br />
when either ELT_NAME or ELT_VERSION contain wild-card characters or null<br />
values. The total number of procedure elements and the number of undeleted<br />
procedure elements are contained in the ACQ_BASIC_PF_INFO return values<br />
NUM_PROC_ELTS and NUM_UNDELETED_PROC_ELTS, respectively.<br />
As described in 2.4.1, the total work area size plus the return area size cannot exceed<br />
approximately 238,000 words.<br />
The maximum defined work area size of 52,000 words allows UNDELETE_ELT to<br />
efficiently process a standard program file with the maximum of 5,000 elements and any<br />
combination of function packet options.<br />
When the maximum possible work area size (about 238,000 words) is specified and<br />
return area size is specified as zero, there is sufficient work area to efficiently process a<br />
large program file with approximately 23,500 elements and any combination of function<br />
packet options.<br />
7830 9796–013 8–23
Updating Program Files<br />
8.4. Pack Program File (PACK_PF)<br />
The PACK_PF function removes from a program file deleted elements, their associated<br />
procedure table entries, if any, and their associated element text. The element text<br />
associated with deleted elements and the space occupied by Object Module Entry Point<br />
Tables are removed by PACK_PF and are sometimes referred to as dead space.<br />
The PACK_PF function exclusively assigns the file on which it operates. Before<br />
modifying the file in any way, the structure of the file is checked for validity. The<br />
function proceeds only if the file passes all validity checks. If the file contains a<br />
Relocatable Entry Point Table, it is removed. If the file contains Object Module Entry<br />
Point Tables, they are removed. If no elements remain after removing deleted elements<br />
from the file and if the file is a standard program file (PF), the function erases the file. If<br />
elements do remain or if the file is a large program file (LPF) or a large element program<br />
file (LEPF), the file retains its structure. After completion, the function returns the<br />
following information:<br />
• Number of elements and amount of mass storage released from the file<br />
• Number and type of elements and procedure table entries remaining in the file<br />
• Number of elements and procedure table entries that can be added to the file<br />
The PACK_PF function can use either the standard method or the copy method to pack<br />
files. An option enables selection of the desired method. Both standard program files<br />
and large program files can be packed using either pack method.<br />
The standard method packs the file in place and is performed in two main steps.<br />
• In the first step, all deleted element table entries and all associated procedure table<br />
entries are removed and the tables are rebuilt and rewritten to mass storage. No<br />
deleted element text is removed during this step.<br />
• In the second step, the text of remaining undeleted elements is copied, if necessary,<br />
so that the text of each element immediately follows the text of the previous<br />
element. This closes up the element text for the file and removes the dead space<br />
previously occupied by deleted element text. After the element text is copied for<br />
each element, the element table entry is updated and is normally written to mass<br />
storage immediately. If the element has associated procedure table entries, they are<br />
updated and are normally written to mass storage immediately. An option is<br />
available to delay the writing of updated element table and procedure table entries to<br />
improve performance.<br />
The copy method packs the file externally using a dynamically assigned temporary file<br />
and is performed in two main steps.<br />
• In the first step, all undeleted element table entries, there associated procedure<br />
table entries, if any, and there associated element text are copied to the temporary<br />
file using the COPY_ELT function.<br />
• In the second step, the entire temporary file is copied back to the original program<br />
file using the COPY_RAF_RAF function. Unique error codes associated with the<br />
copy method are described in A.2.8.<br />
8–24 7830 9796–013
Updating Program Files<br />
If neither the standard method nor the copy method is selected, the PACK_PF function<br />
determines the method to use to pack a file. If there is sufficient work area and if the<br />
program file element table and all procedure tables are less than or equal to 65,436<br />
words in length (6,529 elements, 16,324 procedures, or 8,162 eight-word COBOL<br />
procedures), the standard method is used to pack the file. Otherwise, the copy method<br />
is used.<br />
Each pack method has its own work area requirements, described in 8.5.4. Appendix C<br />
contains additional technical information on the operation of the two pack methods. It<br />
includes a detailed function performance discussion and comparison (C.1, C.2, and C.3)<br />
and a discussion of the contents of the file in case of system failure or function failure<br />
(C.4).<br />
The PACK_PF function provides the following options:<br />
• Do not release mass storage, release unused mass storage back to the initial reserve<br />
of the file, or release all unused mass storage.<br />
• Zero-fill all mass storage before it is released.<br />
• Select the standard method, the copy method, the copy method only if there is<br />
insufficient work area for the standard method, or let the PACK_PF function select<br />
the pack method.<br />
• When the standard method is used, delay writing the updated element table and<br />
procedure table entries to reduce the amount of I/O and improve performance.<br />
The PACK_PF function does not provide the following capabilities of the FURPUR<br />
@PACK command:<br />
• Remove all elements except undeleted elements of a specific type from a program<br />
file. A combination of the A, O, R, or S options on the @PACK command provides<br />
this capability in FURPUR. The same result can be achieved using PCFP by<br />
performing a DELETE_ELT function followed by a PACK_PF function.<br />
• Create a new Relocatable Entry Point Table and a new Object Module Entry Point<br />
Table. The @PACK,P command provides this capability in FURPUR. The same result<br />
can be achieved using PCFP by performing a PACK_PF function followed by a<br />
PREP_PF function.<br />
• Reduce the program file tables to their minimum sizes. The @PACK,M command<br />
provides this capability in FURPUR. This capability is not available in PCFP.<br />
8.4.1. Parameters<br />
The PACK_PF function has the following parameters, each of which is described in the<br />
following subsection:<br />
• Function Packet<br />
• File Identifier<br />
• Work Area<br />
7830 9796–013 8–25
Updating Program Files<br />
8.4.2. Function Packet<br />
The structure of the PACK_PF function is defined in element FP$PACKPF.<br />
See Figure 8–4.<br />
GENERIC PART<br />
0 a b aa bb STORARE_TO_RELEASE<br />
1 NEXT_TEXT_LOCATION<br />
2 TOC_SIZE<br />
3 TEXT_SIZE<br />
4 LATEST_ABS_SEQ_NUM<br />
5 ELT_NUM_ENTRIES ELT_OPEN_ENTRIES<br />
6 MASM_PROC_NUM_ENTRIES MASM_PROC_OPEN_ENTRIES<br />
7 COBOL_PROC_NUM_ENTRIES COBOL_PROC_OPEN_ENTRIES<br />
8 FTN_PLUS_PROC_NUM_ENTRIES FTN_PLUS_PROC_OPEN_ENTRIES<br />
9 REL_EP_NUM_ENTRIES REL_EP_OPEN_ENTRIES<br />
10 NUM_ABS_ELTS NUM_OMN_ELTS<br />
11 NUM_REL_ELTS NUM_SYM_ELTS<br />
12 NUM_DELETED_ELTS<br />
13 DEAD_SPACE<br />
Item Descriptions<br />
Figure 8–4. PACK_PF Function Packet Items<br />
a = ZERO_RELEASED_STORAGE<br />
Indicates whether PCFP zero-fills all mass storage that it releases.<br />
Data Type: condition<br />
b = REDUCE_IO<br />
Indicates whether the standard method writes individual element table entries and<br />
procedure table entries as they are updated (FALSE) or whether writes are delayed<br />
until all program file table updates are complete (TRUE). The effect of this item on<br />
function performance and on the contents of the file in case of system failure or<br />
function failure, is discussed in Appendix C.<br />
Data Type: condition<br />
8–26 7830 9796–013
aa = PACK_METHOD<br />
Indicates the method to be used to pack the file.<br />
Data Type: value-list<br />
DEFAULT = 0<br />
Updating Program Files<br />
The PACK_PF function selects the method to be used, based on the supplied<br />
work area size and the size of the program file tables.<br />
STANDARD = 1<br />
Use the standard method to pack the file.<br />
COPY = 2<br />
Use the copy method to pack the file.<br />
COPY_IF_NECESSARY = 3<br />
Use the standard method to pack the file, unless the supplied work area size is<br />
not sufficient. In this case, use the copy method to pack the file.<br />
bb = METHOD_USED<br />
Indicates the method actually used by the PACK_PF function to pack the file<br />
Data Type: value-list, returned<br />
STANDARD = 1<br />
The standard method was used.<br />
COPY = 2<br />
The copy method was used.<br />
STORAGE_TO_RELEASE<br />
Indicates to what extent PCFP releases unused mass storage from the program file<br />
after the file is packed.<br />
Data Type: value-list<br />
NONE = 0<br />
Does not release any unused mass storage.<br />
ALL_BUT_INITIAL_RESERVE = 1<br />
Releases any unused mass storage above the initial reserve of the file.<br />
7830 9796–013 8–27
Updating Program Files<br />
ALL_STORAGE = 2<br />
Releases all unused mass storage from the file, including any within the initial<br />
reserve.<br />
Note: All remaining items in this function packet contain return values. These items<br />
are the same as those returned by ACQ_BASIC_PF_INFO. Except as indicated, these<br />
items apply to the file after it is packed.<br />
NEXT_TEXT_LOCATION<br />
Indicates the location (in words) where the text of the next element added to the<br />
program file would be written.<br />
Data Type: unsigned integer, returned<br />
TOC_SIZE<br />
Indicates the amount of mass storage (in words) still occupied by the program-file<br />
tables of contents in the program file.<br />
Data Type: unsigned integer, returned<br />
TEXT_SIZE<br />
Indicates the amount of mass storage (in words) occupied by the text of all elements<br />
remaining in the program file.<br />
Data Type: unsigned integer, returned<br />
LATEST_ABS_SEQ_NUM<br />
Indicates the sequence number of the latest absolute element in the program file. A<br />
value of zero implies that the file contains no absolute elements.<br />
Data Type: unsigned integer, returned<br />
ELT_NUM_ENTRIES<br />
Indicates the number of entries remaining in the element table of contents.<br />
Data Type: unsigned integer, returned<br />
ELT_OPEN_ENTRIES<br />
Indicates the number of additional entries the element table of contents could<br />
contain at its currently allocated size. (See notes following item descriptions.)<br />
Data Type: unsigned integer, returned<br />
8–28 7830 9796–013
MASM_PROC_NUM_ENTRIES<br />
Updating Program Files<br />
Indicates the number of entries remaining in the MASM procedure table of contents.<br />
Data Type: unsigned integer, returned<br />
MASM_PROC_OPEN_ENTRIES<br />
Indicates the number of additional entries the MASM procedure table of contents<br />
could contain at its currently allocated size. (See notes following item descriptions.)<br />
Data Type: unsigned integer, returned<br />
COBOL_PROC_NUM_ENTRIES<br />
Indicates the number of entries remaining in the COBOL procedure table of<br />
contents.<br />
Data Type: unsigned integer, returned<br />
COBOL_PROC_OPEN_ENTRIES<br />
Indicates the number of additional entries the COBOL procedure table of contents<br />
could contain at its currently allocated size. (See notes following item descriptions.)<br />
Data Type: unsigned integer, returned<br />
FTN_PLS_PROC_NUM_ENTRIES<br />
Indicates the number of entries remaining in the FORTRAN-PLUS procedure table of<br />
contents.<br />
Data Type: unsigned integer, returned<br />
FTN_PLS_PROC_OPEN_ENTRIES<br />
Indicates the number of additional entries the FORTRAN-PLUS procedure table of<br />
contents could contain at its currently allocated size. (See notes following item<br />
descriptions.)<br />
Data Type: unsigned integer, returned<br />
REL_EP_NUM_ENTRIES<br />
Indicates the number of entries remaining in the relocatable entry point table of<br />
contents. Since PACK_PF removes the entry point tables, this item always has value<br />
0, and is included only to maintain correspondence between this function and<br />
ACQ_BASIC_PF_INFO.<br />
Data Type: unsigned integer, returned<br />
7830 9796–013 8–29
Updating Program Files<br />
REL_EP_OPEN_ENTRIES<br />
Indicates the number of additional entries the relocatable entry point table of<br />
contents could contain at its currently allocated size. Since PACK_PF removes the<br />
entry point tables, this item always has value 0, and is included only to maintain<br />
correspondence between this function and ACQ_BASIC_PF_INFO.<br />
Data Type: unsigned integer, returned<br />
NUM_ABS_ELTS<br />
Indicates the number of absolute elements remaining in the program file.<br />
Data Type: unsigned integer, returned<br />
NUM_OMN_ELTS<br />
Indicates the number of omnibus elements remaining in the program file.<br />
Data Type: unsigned integer, returned<br />
NUM_REL_ELTS<br />
Indicates the number of relocatable elements remaining in the program file.<br />
Data Type: unsigned integer, returned<br />
NUM_SYM_ELTS<br />
Indicates the number of symbolic elements remaining in the program file.<br />
Data Type: unsigned integer, returned<br />
NUM_DELETED_ELTS<br />
Indicates the number of deleted elements of all types that were in the program file<br />
initially, and that were removed by this function.<br />
Data Type: unsigned integer, returned<br />
DEAD_SPACE<br />
Indicates the mass storage (in words) that was released by the function when<br />
STORAGE_TO_RELEASE has a value of ALL_BUT_INITIAL_RESERVE or<br />
ALL_STORAGE. Note that this value is not necessarily the same as the amount of<br />
dead space associated with the deleted elements and Object Module Entry Point<br />
Tables that were removed by this function.<br />
Data Type: unsigned integer, returned<br />
8–30 7830 9796–013
Notes:<br />
Updating Program Files<br />
The following points apply to each item that returns the number of available entries in a<br />
table of contents:<br />
• For a standard program file, if a table is empty (current number of entries is zero), the<br />
value PCFP returns for the number of available entries in the table is also zero, even<br />
though in most cases entries can be added to the table.<br />
• For a standard program file, PCFP calculates the number of available entries by<br />
assuming that all tables that are empty at the end of PACK_PF remain empty. If an<br />
entry is added later to a table that is currently empty, the number of available entries<br />
in other tables may be significantly reduced.<br />
• For a large program file, all tables have fixed sizes and a fixed maximum number of<br />
entries. PCFP calculates the number of available entries by subtracting from the<br />
fixed maximum number the number of entries remaining in the table at the end of<br />
PACK_PF.<br />
• Some tables (for example, the COBOL procedure table) have variable-length entries.<br />
PCFP calculates the number of available entries by assuming entries of maximum<br />
size.<br />
8.4.3. File Identifier<br />
The file identifier parameter names the file to be packed. The named file must be a<br />
program file on sector-addressable mass storage for which the calling program has both<br />
read and write privileges. See 2.3 for a full description of this parameter.<br />
8.4.4. Work Area<br />
The work area requirements of the two pack methods are described in this subsection.<br />
While deciding which method to select, you may want to review Appendix C.<br />
Subsections C.1, C.2, and C.3 describe PACK_PF performance and C.4 describes the<br />
contents of the file in case of a system or function failure.<br />
8.4.4.1. Standard Method Work Area Requirements<br />
The work area required by the PACK_PF standard method depends on the following:<br />
• Number of elements in the file<br />
• Number of procedure tables present<br />
• Number of procedure entries in each table<br />
• Size of the text to copy<br />
The standard method requires enough work area for one copy of the element table, two<br />
copies of each of the procedure tables, and the buffer that is used when copying<br />
element text. All of the information needed to calculate the standard method work area<br />
requirement can be obtained using the ACQ_BASIC_PF_INFO function, described in 6.1.<br />
7830 9796–013 8–31
Updating Program Files<br />
The size of the work area required is calculated by the formula (350 + 10*T + 252*U + V<br />
+ MAX(V,W)), where<br />
T The initial number of elements in the file. This corresponds to the<br />
ACQ_BASIC_PF_INFO return value ELT_NUM_ENTRIES.<br />
U The initial number of procedure tables in the file (0 ≤ U ≤ 3). To calculate U, add<br />
one for each nonzero procedure table value returned by ACQ_BASIC_PF_INFO<br />
(MASM_PROC_NUM_ENTRIES, COBOL_PROC_NUM_ENTRIES, and<br />
FTN_PLS_PROC_NUM_ENTRIES).<br />
V The initial size of the procedure table entries in the file. It is calculated with the<br />
formula (8*X + 4*Y). X is the initial number of 8-word procedure entries in the<br />
COBOL procedure table. This corresponds to the ACQ_BASIC_PF_INFO return<br />
value NUM_8_WORD_COBOL_PROC_ENTRIES. Y is the sum of the initial<br />
number of procedure entries in the MASM procedure table, the initial number of<br />
procedure entries in the FORTRAN/PLUS procedure table, and the initial number<br />
of 4-word procedure entries in the COBOL procedure table. This corresponds to<br />
the sum of ACQ_BASIC_PF_INFO return values MASM_PROC_NUM_ENTRIES,<br />
FTN_PLS_PROC_NUM_ENTRIES, and<br />
NUM_4_WORD_COBOL_PROC_ENTRIES. One buffer this size is required for<br />
both pack steps. A second buffer this size is required for the first pack step<br />
MAX A function that selects the larger of the two values, V or W.<br />
W The I/O buffer that is used to copy element text during the second pack step.<br />
The function operates with any value greater than or equal to the minimum I/O<br />
buffer size (112 words). To maximize performance, W should be the same size in<br />
words as the largest element text associated with an undeleted element, but not<br />
greater than 64,512 words. This corresponds to the ACQ_BASIC_PF_INFO<br />
return value LARGEST_UNDELETED_TEXT_SIZE. Even if the file has very large<br />
elements, a buffer size of four 1,792-word tracks, or 7,168 words, usually<br />
achieves acceptable performance. A buffer size of eight 1,792-word tracks, or<br />
14,336 words, usually achieves good performance and is recommended.<br />
The standard method cannot be used unless sufficient work area is provided to satisfy<br />
the formula with the proper T, U, and V values and the minimum size for W. The<br />
performance of the function improves as W is increased to the size of the largest<br />
element text. Note that for some large program files, the formula may yield a value that<br />
is larger than the maximum possible work area of approximately 238,000 words. In this<br />
case, the file must be packed using the copy method.<br />
8–32 7830 9796–013
Updating Program Files<br />
The following are five examples of program files and the work area that is required to<br />
pack each one using the standard method. Contrast these against the recommended<br />
work area requirements for the same five files using the copy method, described in<br />
8.4.4.2.<br />
1. A program file with 100 elements and one procedure table containing 35 procedure<br />
entries can be packed using the minimum I/O buffer size of 112 words when the<br />
minimum work area of 2,000 words is specified.<br />
2. A filled standard program file with 2,671 undeleted elements and three procedure<br />
tables each containing 861 4-word procedure entries can be packed using an I/O<br />
buffer size of 7,168 words when the maximum work area of 60,000 words is<br />
specified.<br />
3. A filled standard program file with 5,000 undeleted elements and no procedure<br />
tables can be packed using an I/O buffer size of 7,168 words when the maximum<br />
work area of 60,000 words is specified.<br />
4. A large program file with 22,300 elements and no procedure tables can be packed<br />
using an I/O buffer size of 14,336 words when the maximum possible work area of<br />
approximately 238,000 words is specified.<br />
5. A large program file with 10,000 elements and three procedure tables containing a<br />
total of approximately 17,000 procedure entries can be packed using an I/O buffer<br />
size of 64,512 words when the maximum possible work area of approximately<br />
238,000 words is specified.<br />
Program file examples 4 and 5 have tables that are greater than 65,436 words, so you<br />
would specify PACK_METHOD as STANDARD or COPY_IF_NECESSARY to use the<br />
standard method. A value of DEFAULT selects the copy method, even if sufficient work<br />
area is provided.<br />
8.4.4.2. Copy Method Work Area Requirements<br />
The work area required by the PACK_PF copy method is based on the requirements for<br />
the two main PCFP functions that it calls: COPY_ELT and COPY_RAF_RAF.<br />
Unlike the standard method where sufficient work area must be provided to satisfy the<br />
formula, the copy method can be used to pack any format program file of any size<br />
whenever there is a minimum work area of 4,570 words.<br />
However, to maximize performance it is important to use the formulas described in this<br />
subsection to determine the amount of work area to specify.<br />
The work area requirements for the first copy method step are based on the COPY_ELT<br />
work area requirements and are completely described in 7.1.6. The work area<br />
requirements for the second copy method step are based on the COPY_RAF_RAF work<br />
area requirements and are completely described in 5.1.5. After calculating the work area<br />
requirements for both functions, use the larger of the two values to maximize<br />
performance, but not more than the maximum possible value of approximately 238,000.<br />
7830 9796–013 8–33
Updating Program Files<br />
The first copy method step calls the COPY_ELT function to copy undeleted elements to<br />
the temporary file. This work area formula uses the same abbreviations as described in<br />
7.1.6. All of the information needed to calculate the work area requirement can be<br />
obtained using the ACQ_BASIC_PF_INFO function, described in 6.1. The work area<br />
required is calculated by the formula 215 + S + D + I + C, where<br />
215 The fixed function requirement. This is the COPY_ELT requirement of 125 plus 90<br />
words of additional overhead.<br />
S The program file buffer size. This is 252 + 10*J, where J is the initial number of<br />
elements in the program file. This corresponds to the ACQ_BASIC_PF_INFO<br />
return value ELT_NUM_ENTRIES.<br />
D The temporary file buffer size. This is 252 + 10*L, where L is the number of<br />
undeleted elements in the program file. This corresponds to the difference<br />
between ACQ_BASIC_PF_INFO return values ELT_NUM_ENTRIES and<br />
NUM_DELETED_ENTRIES.<br />
I The I/O buffer size. The minimum I/O buffer size is 896 words. To maximize<br />
performance, I should be the size in words of the largest element text associated<br />
with an undeleted element, but not more than 64,512 words. This corresponds to<br />
the ACQ_BASIC_PF_INFO return value LARGEST_UNDELETED_TEXT_SIZE.<br />
Even if the file has very large elements, a buffer size of four 1,792-word tracks, or<br />
7,168 words, usually achieves acceptable performance. A buffer size of eight<br />
1,792-word tracks, or 14,336 words, usually achieves good performance and is<br />
recommended.<br />
C The procedure table copy buffer size. This is 3 + 3*N, where N is the number of<br />
undeleted elements with associated procedure table entries. This corresponds to<br />
the ACQ_BASIC_PF_INFO return value NUM_UNDELETED_PROC_ELTS.<br />
To maximize performance, ensure that the work area recommended for D (temporary file<br />
buffer) and I (I/O buffer) is available. If possible, provide the work area recommended for<br />
C (procedure table copy buffer). If necessary, the work area for S (program file buffer)<br />
can be reduced to its minimum of 252 without too much impact on function<br />
performance.<br />
Note: C in the copy method formula is based on the number of elements that have<br />
associated procedure table entries, while V in the standard method formula (8.4.4.1) is<br />
based on the number of procedure table entries.<br />
8–34 7830 9796–013
Updating Program Files<br />
The second copy method step calls the COPY_RAF_RAF function to copy the temporary<br />
file back to the program file. This work area formula uses the same abbreviations as in<br />
5.1.5. The work area required is calculated by the formula 870 + 3700*N, where<br />
870 The fixed function requirement. This is the COPY_RAF_RAF requirement (K) of<br />
800 for a temporary source file plus 70 words of additional overhead.<br />
N The number of track size buffers to allocate. The minimum value is 1. Acceptable<br />
performance can usually be achieved with a value of 4. The recommended value<br />
is 8.<br />
This formula produces a COPY_RAF_RAF minimum work area requirement value of<br />
4,570, an acceptable value of 15,670, and a recommended value of 30,470. Some<br />
additional performance improvement can be expected with the maximum N value of 16,<br />
yielding a work area value of 60,070.<br />
Generally, the work area recommended for the copy method is larger than the work area<br />
recommended for the standard method (8.4.4.1). This is particularly true for small files.<br />
The recommended value of 30,470 for the second copy method step is usually large<br />
enough for a file containing approximately 750 undeleted elements. For files with more<br />
elements, the recommended value for the first copy method step is usually larger.<br />
For the five program file examples in 8.4.4.1, the following work area sizes would be<br />
recommended to achieve good performance using the copy method:<br />
1. For the file with 100 elements and 35 procedures, the COPY_RAF_RAF<br />
recommended value of 30,470 applies.<br />
2. For the filled standard program file with 2,671 undeleted elements, assuming 100<br />
are procedure elements, the COPY_ELT recommended value of 68,778 is calculated<br />
from the formula. Note that reducing S in the COPY_ELT formula to its minimum<br />
should not seriously affect performance and reduces the total work area value to<br />
42,068.<br />
3. For a filled standard program file with 5,000 undeleted elements and with no<br />
procedure tables, the COPY_ELT recommended value of 115,058 is calculated from<br />
the formula. Reducing S to its minimum reduces the total work area value to<br />
65,058.<br />
4. For the large program file with 22,300 undeleted elements and with no procedure<br />
tables, the maximum possible work area of 238,000 is calculated from the<br />
COPY_ELT formula, even by reducing S to its minimum.<br />
5. For the large program file with 10,000 undeleted elements, assuming 1,000 are<br />
procedure elements, the COPY_ELT recommended value of 218,058 is calculated<br />
from the formula. Reducing S to its minimum reduces the total work area value to<br />
118,058.<br />
7830 9796–013 8–35
Updating Program Files<br />
8.5. Create Program File Entry Point Table<br />
(PREP_PF)<br />
The PREP_PF function builds a relocatable or an object-module entry point table in a<br />
program file. This function corresponds to the FURPUR @PREP command.<br />
This function handles the two entry point tables differently. The process of building a<br />
relocatable entry point table destroys any existing relocatable entry point table. Thus the<br />
table is always rebuilt completely. On the other hand, the process of building the<br />
object-module entry point table always consists of adding to the existing object<br />
module-entry point table.<br />
When building the relocatable entry point table, this function always selects the starting<br />
address of the table such that the table occupies the minimum space needed to<br />
accommodate all of the relocatable entry points. In this way, this function differs from<br />
the FURPUR @PREP command, which always starts this table at the system defined<br />
starting address. The PCFP PREP_PF function may be able to successfully build a<br />
relocatable entry point table for some program files where the FURPUR @PREP<br />
command returns an error.<br />
The following options are provided with this function:<br />
• Creates a relocatable entry point table, an object-module entry point table, or both<br />
tables.<br />
• Creates a relocatable entry point table even if one already exists. (If this option is not<br />
specified, this function does not rebuild the relocatable entry point table when one<br />
already exists, even though the calling program specifically calls for the creation of a<br />
relocatable entry point table.)<br />
This function exclusively assigns the program file upon which it operates.<br />
8.5.1. Parameters<br />
The PREP_PF function has the following parameters, each of which is described in the<br />
following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Work Area<br />
8–36 7830 9796–013
8.5.2. Function Packet<br />
Updating Program Files<br />
The structure of the PREP_PF function packet is defined in element FP$PREPPF. See<br />
Figure 8–5.<br />
GENERIC PART<br />
0 a EP_TYPE<br />
1 REL_EP_CNT DUP_REL_EP_CNT<br />
2 OM_EP_CNT<br />
Item Descriptions<br />
a = OVERWRITE_OLD_EP_TABLE<br />
Figure 8–5. PREP_PF Function Packet Items<br />
Indicates if this function rebuilds the relocatable entry point table when a table exists<br />
previously.<br />
Data Type: condition<br />
EP_TYPE<br />
Indicates which entry point tables this function builds.<br />
Data Type: value-list<br />
REL_EP = 1<br />
Creates only the relocatable entry point table.<br />
OM_EP = 2<br />
Creates only the object-module entry point table.<br />
BOTH = 3<br />
REL_EP_CNT<br />
Creates both relocatable and object-module entry point tables.<br />
Indicates the number of entry points within all of the relocatable elements that the<br />
program file contains. All of these are included in the relocatable entry point table.<br />
This value is zero if the calling program did not request building of the relocatable<br />
entry point table.<br />
Data Type: unsigned integer, returned<br />
7830 9796–013 8–37
Updating Program Files<br />
DUP_REL_EP_CNT<br />
Indicates the number of entry points in all of the relocatable elements within the<br />
program file having names duplicating other entry points within the program file.<br />
This value is zero if the calling program did not request building of the relocatable<br />
entry point table.<br />
Data Type: unsigned integer, returned<br />
OM_EP_CNT<br />
Indicates the number of entry points within all of the object modules that are in the<br />
OM entry point table following the completion of the PREP_PF function.<br />
Data Type: unsigned integer, returned<br />
8.5.3. File Identifier<br />
The file identifier parameter names the file to be prepped. The named file must be a<br />
program file on sector-addressable mass storage for which the calling program has both<br />
read and write privileges. See 2.3 for a full description of this parameter.<br />
8–38 7830 9796–013
8.5.4. Work Area<br />
Updating Program Files<br />
The calling program must supply a work area of 1,500 words if only the object-module<br />
entry point table is built. If the calling program requests the creation of the relocatable<br />
entry point table, either by itself or in conjunction with the object-module entry point<br />
table, the calling program must supply a work area of at least 1,500 or (600 + 8*N)<br />
words, where N is the number of relocatable entry points in the program file.<br />
The maximum defined work area of 26,000 words is adequate to handle a standard size<br />
relocatable entry point table containing up to 3,101 relocatable entry points. However,<br />
when no procedure tables are present in a standard program file the relocatable entry<br />
point table can be expanded to contain up to 5,789 relocatable entry points, which would<br />
require a work area of 47,000 words. Further expansion into unused element table<br />
entries allows a theoretical expansion of the relocatable entry point table to a maximum<br />
of 12,460 relocatable entry points, which would require a work area of 100,000 words. A<br />
large program file has a fixed maximum of 20,125 relocatable entry points, which would<br />
require a work area of 162,000 words.<br />
The specified WORK_AREA_SIZE should not exceed approximately 227,000 words. This<br />
is the approximate maximum size that can be specified for this function, where the<br />
minimum relative address is MIN_DATA_ADDR_WITH_LINK and the maximum relative<br />
address is MAX_DATA_ADDR, as contained in the copy/include element FP$DEFS.<br />
If error FP_ERR_SMALL_PREP_PF_WORK_AREA is returned, this indicates that the<br />
specified WORK_AREA_SIZE is not sufficient for the number of relocatable entry points<br />
in the file. The number of relocatable entry points is returned in item<br />
AUX_ERROR_CODE in the generic part of the function packet (see 2.4.1). You can use<br />
AUX_ERROR_CODE for the value N in the formula (600 + 8*N). This calculates the<br />
WORK_AREA_SIZE required for this file. Call the PREP_PF function again with this<br />
WORK_AREA_SIZE value.<br />
If error FP_ERR_TOC_SPACE_TOO_SMALL is returned, this indicates that the size of the<br />
program file relocatable element entry point table is not sufficient for the number of<br />
relocatable entry points in the file. A relocatable element entry point table cannot be<br />
built for this file unless some of the relocatable elements are deleted with the PCFP<br />
DELETE_ELT function or the FURPUR @DELETE,R command.<br />
7830 9796–013 8–39
Updating Program Files<br />
8–40 7830 9796–013
Section 9<br />
Erasing and Deleting Files<br />
This section describes the following PCFP functions that erase and delete files:<br />
• Erase RAF (ERASE_RAF)<br />
• Delete File (DELETE_FILE)<br />
9.1. Erase RAF (ERASE_RAF)<br />
The ERASE_RAF function releases mass storage from a random-access file. It can also<br />
zero-fill the file storage it releases or the file storage it does not release.<br />
This function operates on cataloged and temporary, sector-addressable, and<br />
word-addressable mass storage files. This function exclusively assigns the file it<br />
operates on.<br />
This function has the following options:<br />
• Release the mass storage associated with the file according to one of the following<br />
schemes:<br />
− Do not release any mass storage.<br />
− Release only mass storage not included in the initial reserve of the file.<br />
− Release all mass storage including the initial reserve.<br />
Note: Select this third alternative to guarantee that a file is entirely empty. The other<br />
two alternatives might leave residual data in the file, which other PCFP functions might<br />
interpret as valid data.<br />
• If mass storage is released from the file, zero-fill it before it is released or do not<br />
change it before it is released.<br />
• If mass storage is retained in the file, zero-fill the first track (1792 words) of the file<br />
and up to the lesser of the highest track written and the highest track retained or<br />
zero-fill only the first sector (28 words) of the file.<br />
• If the first track of the file is retained and if it is the only track to be zero-filled,<br />
zero-fill it unconditionally or zero-fill it only if it was previously written.<br />
7830 9796–013 9–1
Erasing and Deleting Files<br />
The following are considerations when ERASE_RAF operates on word-addressable files:<br />
• The option to release only mass storage not included in the initial reserve is not<br />
available. If it is specified, all mass storage including the initial reserve is released.<br />
• The option to zero-fill retained mass storage will zero-fill to the larger of highest track<br />
written and initial reserve.<br />
9.1.1. Parameters<br />
The ERASE_RAF function has the following parameters, each of which is described in<br />
the following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Work Area<br />
9.1.2. Function Packet<br />
The structure of the ERASE_RAF function packet is defined in element FP$ERSRAF.<br />
See Figure 9–1.<br />
GENERIC PART<br />
0 a b c STORAGE_TO_RELEASE<br />
1 STORAGE_RELEASED<br />
Item Descriptions<br />
Figure 9–1. ERASE_RAF Function Packet Items<br />
a = ZERO_RELEASED_STORAGE<br />
When TRUE, indicates that mass storage is to be zero-filled before it is released.<br />
When FALSE, indicates that mass storage is not changed before it is released. This<br />
item is ignored if no mass storage is released.<br />
Data Type: condition<br />
9–2 7830 9796–013
= ZERO_RETAINED_STORAGE<br />
Erasing and Deleting Files<br />
When TRUE, indicates that the first track of retained mass storage is to be<br />
zero-filled. For sector-addressable files, retained mass storage is zero-filled up to the<br />
lesser of highest track written and highest track retained. For word-addressable<br />
files, retained mass storage is zero-filled up to the greater of the highest track<br />
written and the initial reserve. When FALSE, indicates that only the first sector of<br />
retained mass storage is to be zero-filled. This item is ignored if no mass storage is<br />
retained.<br />
Data Type: condition<br />
c = ZERO_FIRST_TRACK_ONLY_IF_WRITTEN<br />
When only the first track or the first sector of retained mass storage is to be<br />
zero-filled, this item indicates if PCFP should perform additional checks before<br />
writing to the file. When TRUE, the first track or the first sector is zero-filled only if<br />
any part of the first track was previously written. When FALSE, the first track or the<br />
first sector is always zero-filled. This item is ignored if no mass storage is retained or<br />
if retained mass storage is to be zeroed beyond the first track.<br />
Data Type: condition<br />
STORAGE_TO_RELEASE<br />
Indicates to what extent this function releases mass storage from the file.<br />
Data Type: value-list<br />
NONE = 0<br />
Releases no mass storage from the file.<br />
ALL_BUT_INITIAL_RESERVE = 1<br />
For sector-addressable files, release all mass storage beyond the initial reserve<br />
of the file. For word-addressable files, release all mass storage from the file<br />
including the initial reserve.<br />
ALL_STORAGE = 2<br />
Releases all mass storage from the file, including the initial reserve.<br />
STORAGE_RELEASED<br />
Indicates the number of words of mass storage that this function actually released.<br />
Data Type: unsigned integer, returned<br />
7830 9796–013 9–3
Erasing and Deleting Files<br />
9.1.3. File Identifier<br />
The file identifier parameter names the file to be erased. The named file must be a mass<br />
storage file for which the calling program has write privileges. If the<br />
ZERO_FIRST_TRACK_ONLY_IF_WRITTEN item is TRUE, the calling program also needs<br />
to have read privileges for the file. See 2.3 for a description of this parameter.<br />
9.1.4. Work Area<br />
The ERASE_RAF function requires a work area of 1,000 words.<br />
9.2. Delete File (DELETE_FILE)<br />
This DELETE_FILE function deletes a specified file. It operates on all file types. It<br />
handles both cataloged and temporary files.<br />
The following options are provided with this function:<br />
• Does not perform the deletion if the file is assigned by other users.<br />
• Zero-fills all mass storage before the file is deleted. This option is applicable only for<br />
mass storage files.<br />
This function can operate on a mass storage file that is unloaded, unless the option to<br />
zero-fill the file is selected. If that option is selected, the function causes the file to be<br />
rolled in.<br />
9.2.1. Parameters<br />
The DELETE_FILE function has the following parameters, each of which is described in<br />
the following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Work Area<br />
9–4 7830 9796–013
9.2.2. Function Packet<br />
Erasing and Deleting Files<br />
The structure of the DELETE_FILE function packet is defined in element FP$DELFIL.<br />
See Figure 9–2.<br />
0 a b<br />
Item Descriptions<br />
a = EXCLUSIVE_ASSIGN<br />
GENERIC PART<br />
Figure 9–2. DELETE_FILE Function Packet Items<br />
Indicates whether PCFP must exclusively assign the file to be deleted prior to<br />
deleting it to ensure that no other runs have the file assigned.<br />
Data Type: condition<br />
b = ZERO_RELEASED_STORAGE<br />
Indicates if PCFP zero-fills all mass storage in the file prior to deleting the file. The<br />
calling program can set this item to TRUE only if it also sets EXCLUSIVE_ASSIGN =<br />
TRUE. PCFP ignores this item if the file is not a mass storage file. If this item is<br />
TRUE and the file is unloaded, PCFP rolls in the file before deletion. If this item is<br />
FALSE and the file is unloaded, PCFP deletes the file without rolling it in.<br />
Data Type: condition<br />
9.2.3. File Identifier<br />
The file identifier parameter names the file to be deleted. The calling program must have<br />
write privileges for this file. See 2.3 for a complete description of this parameter.<br />
9.2.4. Work Area<br />
The DELETE_FILE function requires a work area of 1,000 words.<br />
7830 9796–013 9–5
Erasing and Deleting Files<br />
9–6 7830 9796–013
Section 10<br />
Positioning and Closing Tape Files<br />
This section describes the following functions that reposition and close tape files.<br />
• Move SAF (MOVE_SAF)<br />
• Close SAF (CLOSE_SAF)<br />
10.1. Move SAF (MOVE_SAF)<br />
The MOVE_SAF function repositions a tape file forward or backward through a specified<br />
number of logical files stored on the tape file. It can also reposition a tape file to its<br />
physical start (load point) or its logical end. For tape subsystems that support fast tape<br />
access, MOVE_SAF can use a previously saved block-id to quickly reposition a tape file.<br />
The MOVE_SAF function returns the following information:<br />
• Identifier of the current volume (reel or cartridge) after the move<br />
• The volume-relative position of the logical file to which PCFP positioned the tape file<br />
• The block-id that corresponds to the final tape position after the move<br />
• The number of logical files through which PCFP actually moved the tape file<br />
• The number of swaps PCFP performed<br />
The MOVE_SAF function has the following options:<br />
• Move the tape file in one of the following ways:<br />
− Forward N logical files from the current position (N must be ≥ 0)<br />
− Backward N logical files from the current position (N must be > 0)<br />
− To the logical end of the tape file (immediately beyond the last logical file on the<br />
tape file)<br />
− To the physical start of the tape file (that is, rewind the tape file)<br />
− To a previously saved block-id<br />
• Moving backward is not allowed for quarter-inch-cartridge tape files.<br />
7830 9796–013 10–1
Positioning and Closing Tape Files<br />
• Either limits the move to the current volume (that is, does not perform volume<br />
swaps) or moves through multiple volumes if necessary (that is, performs volume<br />
swaps, if necessary). When a tape is moved backwards, only the first alternative is<br />
allowed.<br />
If the calling program request indicates a move to logical end of file, and also limits<br />
the move to the current volume, PCFP returns an error if the logical end of the file is<br />
not on the current volume.<br />
• If PCFP attempts to swap beyond the last volume of the file (because the physical<br />
end of the last volume is reached before the logical end of the tape file), it can take<br />
one of the following actions:<br />
− Return with error status. (In this case, the tape file remains positioned at the<br />
physical end of the last volume.)<br />
− Dynamically extend the tape file. (PCFP solicits the operator for the identifier of<br />
the next volume to allow processing of the remainder of the tape file.)<br />
• At the end of the move, PCFP can position the tape file either at the physical start or<br />
at the physical end of the logical file to which the tape file was moved. (The second<br />
alternative corresponds to the action of the FURPUR @MOVE,B command, and is<br />
allowed only when moving backward from the current position. The first alternative<br />
causes the tape file to be positioned ready for a copy operation, which is the action<br />
usually desired.)<br />
• Return the block-id that corresponds to the final position after the move. The<br />
block-id can be saved and used later to quickly position the tape to the same<br />
position.<br />
The following options apply only when moving to the start of (rewinding) a tape file:<br />
• Rewinds to the start of the first volume of the file, or only rewinds to the start of the<br />
current volume.<br />
• Rewinds with or without interlock. (You cannot use a tape file rewound with<br />
interlock again unless you free and re-assign it.)<br />
This function returns the warning FP_WARN_AT_SAF_END (11) whenever it positions<br />
the tape file at its logical end. It returns the warning FP_WARN_AT_VOL_START (13)<br />
whenever it positions the tape file at the start of any volume of the file.<br />
10.1.1. Parameters<br />
The MOVE_SAF function has the following parameters, each of which is described in the<br />
following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Work Area<br />
10–2 7830 9796–013
10.1.2. Function Packet<br />
Positioning and Closing Tape Files<br />
The structure of the MOVE_SAF function packet is defined in element FP$MOVSAF.<br />
See Figure 10–1.<br />
Note: Figure 10–1 shows the new format function packet that is used when<br />
INTERFACE_LEVEL has value of at least FP_INTERFACE_LEVEL_3. A new function<br />
packet definition must be used when specifying the new interface level.<br />
• For C users, the definition name is fp_move_saf_3_type and the corresponding<br />
function prototype name is _fp_move_saf_3.<br />
• For COBOL users, the definition name is FP-MOVE-SAF-3.<br />
• For FORTRAN users, the definition name is FP$MOVSAF3.<br />
If you modify an existing MOVE_SAF function to use an INTERFACE_LEVEL value of<br />
FP_INTERFACE_LEVEL_3, you must also modify the return function packet definition to<br />
use the new definition name. For compatibility, the previous definition names are<br />
unchanged and describe the interface level 1 and 2 function packets. The format of the<br />
interface level 1 and 2 function packets is described in the previous definitions.<br />
0 a b c d<br />
GENERIC PART<br />
1 TYPE_OF_MOVE ON_END_OF_FILE<br />
2 MOVE_NUM<br />
3 NUM_FILES_MOVED<br />
4 LOGICAL_FILE_POSITION<br />
5 VOL_ID<br />
6 VOL_ID NUM_SWAPS<br />
7 MOVE_BLOCK_ID<br />
8 BLOCK_ID<br />
Figure 10–1. MOVE_SAF Function Packet Items<br />
7830 9796–013 10–3
Positioning and Closing Tape Files<br />
Item Descriptions<br />
INTERFACE_LEVEL<br />
Contained in the GENERIC PART of the function packet and indicates the level of the<br />
packet. The calling program should set this item to the value<br />
FP_INTERFACE_LEVEL_3.<br />
• If this item is set to FP_INTERFACE_LEVEL_1, then<br />
− RETURN_BLOCK_ID must be FALSE<br />
− TYPE_OF_MOVE cannot be set to TO_BLOCK_ID<br />
− MOVE_BLOCK_ID is ignored<br />
− BLOCK_ID is not returned<br />
− The function packet has a format different than that shown in Figure 10–1<br />
• If this item is set to FP_INTERFACE_LEVEL_2, the function packet has a format<br />
different than that shown in Figure 10–1<br />
Data Type: unsigned integer<br />
a = CURRENT_VOL_ONLY<br />
If the calling program sets this item to TRUE, the movement done by this function is<br />
confined to the currently mounted volume. Swapping of volumes cannot occur. If<br />
the calling program sets this item to TRUE and also sets TYPE_OF_MOVE =<br />
TO_SAF_START (rewind), this function positions the tape to the start of the current<br />
volume of the file. See Table 10–1 in 10.1.3 to determine the effect of this item in<br />
combination with other items.<br />
Data Type: condition<br />
b = POSITION_AT_END_OF_LOG_FILE<br />
If the calling program sets this item to TRUE, this function positions the tape file at<br />
the physical end of the logical file to which it moved the tape. If the calling program<br />
sets this item to FALSE, this function positions the tape file at the physical start of<br />
the logical file to which it moved the tape. The calling program can set this item to<br />
TRUE only if it also set TYPE_OF_MOVE = BACKWARD. See Table 10–1 in 10.1.3<br />
to determine the effect of this item in combination with other items.<br />
Data Type: condition<br />
c = INTERLOCK<br />
If the calling program sets this item to TRUE, PCFP rewinds the tape file with<br />
interlock. The calling program can set this item to TRUE only if it also set<br />
TYPE_OF_MOVE = TO_SAF_START.<br />
Data Type: condition<br />
10–4 7830 9796–013
d = RETURN_BLOCK_ID<br />
Positioning and Closing Tape Files<br />
If TRUE, PCFP returns the block-id that corresponds to the final position after the<br />
move. This item can be TRUE only if INTERFACE_LEVEL has a value of at least<br />
FP_INTERFACE_LEVEL_2.<br />
Data Type: condition<br />
TYPE_OF_MOVE<br />
Indicates the type of tape movement PCFP performs. See Table 10–1 in 10.1.3 to<br />
determine the effect of this item in combination with other items.<br />
Data Type: value list<br />
FORWARD = 0<br />
Indicates that PCFP moves the tape file forward from its current position.<br />
MOVE_NUM indicates the number of logical files through which PCFP moves<br />
the tape.<br />
BACKWARD = 1<br />
Indicates that PCFP moves the tape file backward from its current position.<br />
MOVE_NUM, which must be greater than zero, indicates the number of logical<br />
files through which PCFP moves the tape.<br />
TO_SAF_END = 2<br />
Indicates that PCFP positions the tape file at its logical end. At this position, you<br />
can extend the tape file by copying another logical file to it. (The logical end of a<br />
tape file is the position immediately following the last logical file on the tape.)<br />
TO_SAF_START = 3<br />
Indicates that PCFP positions the tape file at its physical beginning. The item<br />
CURRENT_VOL_ONLY controls whether PCFP positions the tape at the start of<br />
either the current volume or the first volume.<br />
TO_BLOCK_ID = 4<br />
Indicates that PCFP should position the tape with the fast tape access Locate<br />
Block (LBLK$) I/O function to the block-id indicated in MOVE_BLOCK_ID. This<br />
value can be specified only if INTERFACE_LEVEL has a value of at least<br />
FP_INTERFACE_LEVEL_2. See 10.1.6 for special considerations relating to this<br />
type of tape positioning.<br />
7830 9796–013 10–5
Positioning and Closing Tape Files<br />
ON_END_OF_FILE<br />
Indicates what action PCFP takes if it encounters the physical end of the last volume<br />
of the tape file before the logical end of the file.<br />
Data Type: value-list<br />
RTN_ERROR = 0<br />
Indicates that PCFP positions the file at the physical end of the last volume, and<br />
returns an error status to the calling program.<br />
EXTEND_TO_BLANK_VOLUME = 1<br />
MOVE_NUM<br />
Indicates that PCFP extends the tape file by requesting a BLANK volume.<br />
System actions on this request depend on many factors, including but not<br />
limited to<br />
• Labeled or unlabeled tape<br />
• Specifications on the tape file @ASG<br />
• Freestanding or library tape unit<br />
• System configuration parameters<br />
• Presence of Media Manager<br />
• Site unique procedures<br />
For compatibility, the previous value name SOLICIT_OPR can also be used.<br />
Indicates the number of logical files through which PCFP moves the tape file. If the<br />
calling program sets TYPE_OF_MOVE = TO_SAF_END, TO_SAF_START, or<br />
TO_BLOCK_ID, it must set this item to zero. If the calling program sets<br />
TYPE_OF_MOVE = BACKWARD, it must set this item to a value greater than zero.<br />
Data Type: unsigned integer<br />
NUM_FILES_MOVED<br />
This item gives the number of logical files between the original tape position and the<br />
new tape position (either forward or backward). This item is unknown and is set to<br />
zero under the following conditions:<br />
• If TYPE_OF_MOVE = TO_SAF_START and CURRENT_VOL_ONLY = FALSE<br />
• If TYPE_OF_MOVE = TO_SAF_START and if the tape has been positioned using<br />
the Locate Block (LBLK$) I/O function<br />
• If TYPE_OF_MOVE = TO_BLOCK_ID<br />
Data Type: unsigned integer, returned<br />
10–6 7830 9796–013
LOGICAL_FILE_POSITION<br />
Positioning and Closing Tape Files<br />
Indicates the volume-relative position of the logical file to which this function<br />
positioned the tape file. This item is unknown and is set to zero under the following<br />
conditions:<br />
VOL_ID<br />
• If TYPE_OF_MOVE = TO_BLOCK_ID<br />
• If the tape is unlabeled and has been positioned using the Locate Block (LBLK$)<br />
I/O function, and if this MOVE_SAF function did not position the tape to its<br />
physical start (load point)<br />
Data Type: unsigned integer, returned<br />
Indicates the identifier of the volume to which this function positioned the tape file.<br />
If the tape file was assigned with a BLANK volume identifier and if the tape file has<br />
not been previously read or written and if the TYPE_OF_MOVE specified is<br />
TO_SAF_START, then a null value is returned for this item.<br />
Data Type: characters (6), returned<br />
NUM_SWAPS<br />
This item gives the number of volume swaps PCFP did during execution of the<br />
function. The value PCFP returns in this item is meaningful only if the calling<br />
program set TYPE_OF_MOVE = FORWARD or TO_SAF_END, and<br />
CURRENT_VOL_ONLY = FALSE.<br />
Data Type: unsigned integer, returned<br />
MOVE_BLOCK_ID<br />
Indicates the block-id to use for fast tape access positioning when TYPE_OF_MOVE<br />
= TO_BLOCK_ID. This item must be zero for all other TYPE_OF_MOVE values. This<br />
item is ignored if INTERFACE_LEVEL has a value of FP_INTERFACE_LEVEL_1.<br />
Data Type: signed integer<br />
7830 9796–013 10–7
Positioning and Closing Tape Files<br />
BLOCK_ID<br />
Indicates the block-id that corresponds to the final position after the move. This item<br />
can have the following values:<br />
• Zero when the function packet RETURN_BLOCK_ID item is FALSE<br />
• Negative one (-1) if fast tape access is not supported for the tape file<br />
• Negative two (-2) if this is a labeled tape and if the final position is at the logical<br />
end of the tape<br />
• A positive integer for valid block-ids<br />
A valid block-id can be saved and used later with TYPE_OF_MOVE = TO_BLOCK_ID<br />
to quickly move to this position. This item can be returned only if<br />
INTERFACE_LEVEL has a value of at least FP_INTERFACE_LEVEL_2.<br />
Data Type: signed integer, returned<br />
10–8 7830 9796–013
Positioning and Closing Tape Files<br />
10.1.3. Actions Performed by the MOVE_SAF Function<br />
TYPE_OF_MOVE<br />
Table 10–1 indicates the actions taken by PCFP depending on the values to which the<br />
calling program sets the items TYPE_OF_MOVE, CURRENT_VOL_ONLY, and<br />
POSITION_AT_END_OF_LOG_FILE.<br />
Table 10–1. Actions Performed by MOVE_SAF Function<br />
CURRENT_<br />
VOL_ONLY<br />
POSITION_AT_END_<br />
OF_LOG_FILE<br />
Action Taken by PCFP<br />
FORWARD false false Move forward past N EOF marks; swap<br />
volumes as necessary.<br />
false true Error—illegal combination of options.<br />
true false Move forward past N EOF marks; error if a<br />
swap is necessary.<br />
true true Error—illegal combination of options.<br />
BACKWARD false false Error—illegal combination of options.<br />
false true Error—illegal combination of options.<br />
true false Move backward past N+1 EOF marks; error if<br />
start of volume is encountered. Next, move<br />
forward past one EOF mark.<br />
true true Move backward past N EOF marks; error if<br />
start of volume is encountered.<br />
TO_SAF_END false false Move forward until logical-end indicator is<br />
encountered; swap volumes as necessary.<br />
false true Error — illegal combination of options.<br />
true false Move forward until logical-end indicator is<br />
encountered; error if swap is required.<br />
true true Error—illegal combination of options.<br />
TO_SAF_START false false Issue ER TINTL$, which mounts the first<br />
volume of the file. The current position is set<br />
to the start of that volume.<br />
false true Error—illegal combination of options.<br />
true false Issue rewind I/O request, which sets the<br />
current position to the start of the current<br />
volume.<br />
true true Error—illegal combination of options.<br />
TO_BLOCK_ID false false Error—illegal combination of options.<br />
false true Error—illegal combination of options.<br />
true false Use LBLK$ to position to MOVE_BLOCK_ID.<br />
true true Error—illegal combination of options.<br />
7830 9796–013 10–9
Positioning and Closing Tape Files<br />
10.1.4. File Identifier<br />
The file identifier parameter names the file to be positioned. The named file must be a<br />
tape file for which the calling program has read privileges. See 2.3 for a complete<br />
description of this parameter.<br />
10.1.5. Work Area<br />
The MOVE_SAF function requires a work area of 1,000 words.<br />
10.1.6. Fast Tape Access Considerations<br />
Fast tape access features are available in all of the PCFP tape functions (CLOSE_SAF,<br />
COPY_RAF_SAF, COPY_SAF_RAF, COPY_SAF_SAF, and MOVE_SAF). All of these<br />
functions allow the caller to set the function packet RETURN_BLOCK_ID = TRUE to<br />
return a block-id that identifies the position of the tape. Later, the MOVE_SAF function<br />
can be called with TYPE_OF_MOVE = TO_BLOCK_ID, and MOVE_BLOCK_ID set to the<br />
previously returned block-id. The Locate Block (LBLK$) I/O function is used by PCFP to<br />
quickly position the tape to the saved location.<br />
The following are important considerations related to fast tape access operations:<br />
• Fast tape access is available on all supported half-inch cartridge tape subsystems.<br />
• To ensure correct operations, block-ids should always be saved with their associated<br />
volume-ids.<br />
• Special privileges are required to perform the LBLK$ I/O function. If the MOVE_SAF<br />
function is called with TYPE_OF_MOVE = TO_BLOCK_ID and the caller does not<br />
have the required privileges, an error fp_err_no_locate_block_priv (error code 2346) is<br />
returned.<br />
− For systems with Fundamental Security (SENTRY_CONTROL = FALSE), the<br />
caller must be running under the overhead account or the security officer<br />
account or must have SYS$*DLOC$ assigned to the run with the correct read<br />
and write keys.<br />
− For systems with Security Option 1, 2, or 3 (SENTRY_CONTROL = TRUE), the<br />
special privileges bypass_tape_hdr1_read_checks (SSBHDR1RDCHK) and<br />
bypass_object_reuse (SSBYOBJREUSE) are required.<br />
• No special privilege is required to return block-id for any of the PCFP tape functions.<br />
• When the MOVE_SAF function is called with TYPE_OF_MOVE = TO_BLOCK_ID,<br />
there is no tape position validation, as there is with the other TYPE_OF_MOVE<br />
values. It is, therefore, important to ensure that the correct volume is mounted<br />
when performing the TYPE_OF_MOVE = TO_BLOCK_ID<br />
10–10 7830 9796–013
Positioning and Closing Tape Files<br />
• Once an LBLK$ I/O function has been performed, special conditions are set by the<br />
Exec. These conditions remain in effect until the tape is returned to its physical start<br />
(load point). Typically, the MOVE_SAF function is called with TYPE_OF_MOVE =<br />
TO_SAF_START to move a tape to load point. The following are special conditions<br />
and how they affect PCFP operations:<br />
− The tape becomes write inhibited. An attempt to write to the tape using the<br />
COPY_RAF_SAF, COPY_SAF_SAF or CLOSE_SAF functions results in an<br />
fp_err_locate_block_done error (error code 2344). The tape can be read using<br />
the COPY_SAF_RAF and COPY_SAF_SAF functions.<br />
− Once a tape is positioned with LBLK$, it is not possible to determine exactly<br />
what precedes this position. The relative position of this file on the tape is,<br />
therefore, unknown and LOGICAL_FILE_POSITION is returned as zero on the<br />
ACQ_FILE_INFO and ACQ_FILE_LIST functions (see 3.1.4.4), on the<br />
COPY_SAF_RAF and COPY_SAF_SAF functions (see 5.3.5), and on the<br />
MOVE_SAF function (see 10.1.2).<br />
− Tape labeling is disabled if this is a labeled tape.<br />
− If the tape is labeled, the only MOVE_SAF function TYPE_OF_MOVE values<br />
allowed are TO_SAF_START and TO_BLOCK_ID. Other TYPE_OF_MOVE values<br />
result in an fp_err_locate_block_done error (error code 2344).<br />
− If the tape is unlabeled, all MOVE_SAF function TYPE_OF_MOVE values can be<br />
used. However, until the tape is returned to load point, the<br />
LOGICAL_FILE_POSITION is unknown and is set to zero.<br />
− If the tape is labeled, once a file has been read with a COPY_SAF_RAF or<br />
COPY_SAF_SAF function, it must be repositioned with a MOVE_SAF function<br />
with TYPE_OF_MOVE = TO_BLOCK_ID before another file on the tape can be<br />
read.<br />
• In most cases LBLK$ positioning is much faster than the equivalent forward space<br />
file (FSF$) and back space file (BSF$) I/O functions used with the MOVE_SAF<br />
function TYPE_OF_MOVE = FORWARD, BACKWARD, and TO_SAF_END.<br />
However, for some older tape equipment types, if the destination of the LBLK$ is<br />
close to the current position of the tape, the LBLK$ may actually be slower than the<br />
equivalent FSF$/BSF$ I/O functions. In some extreme cases, the LBLK$ may<br />
actually cause the tape to rewind to load point and search forward slowly. The tape<br />
equipment types that can encounter this performance problem are styles 5073-02,<br />
5073-03, 5073-SSI, 5073-LSI and USR-5073-xxx, commonly identified as U40 tape<br />
equipment.<br />
7830 9796–013 10–11
Positioning and Closing Tape Files<br />
10.2. Close SAF (CLOSE_SAF)<br />
The CLOSE_SAF function is primarily intended for use with unlabeled tapes:<br />
• When the caller sets the COPY_RAF_SAF and COPY_SAF_SAF function packet item<br />
OMIT_LOG_END_MARK to TRUE, the CLOSE_SAF function must be used to write a<br />
logical end sequence on a tape when copy operations are complete. This is a<br />
technique for improving performance when writing files to an unlabeled destination<br />
tape. If the CLOSE_SAF function is followed by another COPY_RAF_SAF or<br />
COPY_SAF_SAF function, the logical end sequence will be overwritten and another<br />
CLOSE_SAF function will be required.<br />
Note: The failure to write a logical end sequence on a tape can result in a tape loss<br />
of position and an unrecoverable I/O error when the last file on the tape is read.<br />
• When the caller sets the COPY_RAF_SAF and COPY_SAF_SAF function packet item<br />
OMIT_LOG_END_MARK to FALSE, the CLOSE_SAF function is not required.<br />
The CLOSE_SAF function provides the option of returning the block-id of the logical end<br />
sequence. It should be noted that this block-id cannot be used later with the<br />
MOVE_SAF function to position the tape to write additional files on the tape. This is<br />
because the tape becomes write-inhibited following the locate block (LBLK$) I/O<br />
function, as described in 10.1.6.<br />
The CLOSE_SAF function provides the option of ensuring that all data has been written<br />
from the tape buffer to the physical tape after writing the logical end sequence. This is<br />
known as synchronizing the host system and the tape drive and is normally done at the<br />
end of each tape file by the Exec or by the tape subsystem. However, when the<br />
BUFTAP buffered-write mode is enabled for the tape, the Exec improves tape write<br />
performance by inhibiting this synchronization. When you select this option and BUFTAP<br />
is enabled, unlabeled and labeled tapes operate as follows:<br />
• For unlabeled tapes, this option is ignored since the logical end sequence written<br />
includes a move backward (MB$) I/O function that causes the tape subsystem to<br />
implicitly perform synchronization.<br />
• For labeled tapes, this option performs synchronization after the logical end<br />
sequence is written. However, the write end-of-file (WEF$) I/O function used to<br />
write the logical end sequence creates a null file at the end of the tape. A null file<br />
contains Exec tape labeling system header label blocks and trailer label blocks but no<br />
user data blocks. If a null file is not desired at the end of the tape, then the last<br />
COPY_RAF_SAF or COPY_SAF_SAF function to write to the tape should set the<br />
function packet item SYNCHRONIZE to TRUE, as described in 5.2.2 and 5.4.2,<br />
respectively, and the CLOSE_SAF function should not be called.<br />
10–12 7830 9796–013
10.2.1. Parameters<br />
Positioning and Closing Tape Files<br />
The CLOSE_SAF function has the following parameters, each of which is described in<br />
the following subsections:<br />
• Function Packet<br />
• File Identifier<br />
• Work Area<br />
10.2.2. Function Packet<br />
The structure of the CLOSE_SAF function packet is defined in element FP$CLSSAF.<br />
See Figure 10–2.<br />
GENERIC PART<br />
0 FORMAT a b<br />
1 BLOCK_ID<br />
Item Descriptions<br />
INTERFACE_LEVEL<br />
Figure 10–2. CLOSE_SAF Function Packet Items<br />
Contained in the GENERIC PART of the function packet and indicates the level of the<br />
packet. The calling program should set this item to the value<br />
FP_INTERFACE_LEVEL_2.<br />
If this item is set to FP_INTERFACE_LEVEL_1, then<br />
• RETURN_BLOCK_ID must be FALSE.<br />
• SYNCHRONIZE must be FALSE.<br />
• The item BLOCK_ID is not returned.<br />
Data Type: unsigned integer<br />
FORMAT<br />
Indicates the format of the logical-end mark PCFP writes to the tape file.<br />
Data Type: value-list<br />
FURPUR = 1<br />
This is currently the only value to which the calling program can set this item.<br />
7830 9796–013 10–13
Positioning and Closing Tape Files<br />
a = RETURN_BLOCK_ID<br />
If TRUE, PCFP returns the block-id that corresponds to the position of the logical end<br />
sequence. This item can be TRUE only if INTERFACE_LEVEL has a value of at least<br />
FP_INTERFACE_LEVEL_2.<br />
Data Type: condition<br />
b = SYNCHRONIZE<br />
If TRUE and if the buffered-write mode BUFTAP is enabled, after writing the logical<br />
end sequence, ensure that all buffered data has been successfully written to tape. If<br />
necessary, a synchronize (FSAFE$) I/O function is issued. This item is ignored if the<br />
buffered-write mode is BUFOFF, BUFON, or BUFFIL. This item is also ignored for<br />
unlabeled tapes. In these cases, the system and the tape are implicitly synchronized<br />
by the Exec or by the tape subsystem. This item can be TRUE only if<br />
INTERFACE_LEVEL has a value of at least FP_INTERFACE_LEVEL_2.<br />
Data Type: condition<br />
BLOCK_ID<br />
Indicates the block-id that corresponds to the position of the logical end sequence.<br />
This item can have the following values:<br />
• Zero when the RETURN_BLOCK_ID item is FALSE<br />
• Negative one (-1) if fast tape access is not supported for the tape file<br />
• A positive integer for valid block-ids<br />
This item can be returned only if INTERFACE_LEVEL has a value of at least<br />
FP_INTERFACE_LEVEL_2.<br />
Data Type: signed integer, returned<br />
10.2.3. File Identifier<br />
The file identifier parameter names the file to be closed. The named file must be a tape<br />
file for which the calling program has read and write privileges. See 2.3 for a complete<br />
description of this parameter.<br />
10.2.4. Work Area<br />
The CLOSE_SAF function requires a work area of 1,000 words.<br />
10–14 7830 9796–013
Section 11<br />
Using PCFP with C<br />
This section contains information about using PCFP with programs written in C.<br />
11.1. Include Considerations<br />
All PCFP include elements used by C programs have a version name of H, and all have<br />
names beginning with the characters fp$. These elements are all contained in the file<br />
SYS$LIB$*PROC$, which is searched automatically by the UC compiler. Thus, it is not<br />
necessary to code the file name in the #include statement. The recommended form for<br />
coding #include statements for PCFP definition elements is:<br />
#include <br />
where xxxxxxxxx represents the specific part of the element name.<br />
The following PCFP elements must be included in most or all programs that call PCFP.<br />
Prior to these elements, your program must also include the common standard header,<br />
stddef.h.<br />
• fp$defs.h<br />
This element contains definitions of constants, enumeration lists, and structures that<br />
are used by all PCFP functions. You must include this element in every program that<br />
calls PCFP before any other PCFP element.<br />
• fp$errors.h<br />
This element contains constant definitions of error and warning codes that PCFP can<br />
return. This element is optional; you are required to include it in your program only if<br />
your program refers to specific error and warning codes by their defined names.<br />
• fp$file$id.h<br />
This element contains the typedef definition of the file identifier structure, which is<br />
used as a parameter by most PCFP functions. You must include this element in any<br />
program that calls a PCFP function that has one or more file identifier parameters.<br />
• fp$generic.h<br />
This element contains the typedef definition of the generic part of the PCFP function<br />
packet. You must include this element in every program that calls a PCFP function<br />
before any element that defines a specific function packet.<br />
7830 9796–013 11–1
Using PCFP with C<br />
• fp$rtn$info.h<br />
This element contains the typedef definition of the return-information portion of the<br />
PCFP function packet. This portion of the function packet exists only for those<br />
functions that have a return-area parameter. You must include this element in every<br />
program that calls one of these PCFP functions before any element that defines a<br />
specific function packet that contains the return-information portion.<br />
• fp$fffffffff.h<br />
This name refers to each of the elements that contains the typedef definition of a<br />
specific function packet. Each of these elements also contains the function<br />
prototype definition and the work area requirements for the function. Exactly one of<br />
these elements exists for each PCFP function. fffffffff signifies an abbreviated<br />
mnemonic for the function with which the include element is associated. You must<br />
include one of these elements in your program for each different PCFP function that<br />
it calls. You need not include elements for any PCFP functions that your program<br />
does not call.<br />
• fp$rtn$rrrrr.h<br />
This name refers to the elements that contain the typedef definitions of the<br />
repeating structures that certain PCFP functions return. One of these include<br />
elements exists for each unique structure that PCFP can return. rrrrr is an<br />
abbreviated mnemonic for the structure defined by the element. You need include<br />
only those elements of this set that are used by the PCFP functions that your<br />
program calls. The function descriptions in Sections 3 – 10 state which return<br />
structures are used with each PCFP function.<br />
The following example illustrates the #include statements required before your program<br />
calls the acq_elt_info function. Note that this function has a return-area parameter, and<br />
therefore requires inclusion of elements to define the return-information portion of the<br />
function packet, and the return_elt_info structure.<br />
#include <br />
#include <br />
#include /*optional*/<br />
#include <br />
#include <br />
#include <br />
#include <br />
11.2. Naming Conventions<br />
For C programs, the names of all functions, structures, items, and constants used by<br />
PCFP are lowercase. The exceptions are the global constants TRUE, FALSE, and NULL,<br />
which are all uppercase. All globally defined names begin with the characters fp_ or<br />
_fp_. Avoid defining names starting with these characters in programs that call PCFP, so<br />
that there are no conflicts between the names you define, and the names defined for<br />
PCFP.<br />
11–2 7830 9796–013
11.2.1. Function Names<br />
Using PCFP with C<br />
For C programs, the names of all PCFP functions are identical to the function names<br />
given in Sections 3 – 10, except that the C names are in lowercase, and are prefixed with<br />
the characters _fp_.<br />
11.2.2. Typedef Names<br />
For C programs, the names of all PCFP typedef structures start with the characters fp_,<br />
and end with the characters _type. The names of all PCFP typedef enumeration lists<br />
start with fp_, and end with _list.<br />
11.2.3. Item Names<br />
For C programs, the names of all items within structures are exactly the same as shown<br />
in Sections 2 – 10, except that all letters in the names are lowercase. Item names do<br />
not have the fp_ prefix, since each item name can be qualified by the structure that<br />
contains it, and hence does not need to be globally unique.<br />
11.2.4. Names of Constants<br />
For C programs, the names of all PCFP constants start with the prefix fp_. In addition,<br />
for those constants that are part of a list of constants, the characters fp_ are followed by<br />
a short abbreviation that identifies the list to which the constant belongs. This naming<br />
scheme assures the global uniqueness of all constant names.<br />
Constant names that are used by multiple PCFP functions are defined in include element<br />
fp$defs.h (except error and warning codes, which are defined in fp$errors.h). Constant<br />
names that are associated only with a single structure usually are defined in the include<br />
element that defines that structure.<br />
The following prefixes are used for those constants that are part of a list of constants:<br />
fp_err_<br />
PCFP error codes<br />
fp_warn_<br />
PCFP warning codes<br />
fp_cycle_<br />
File and element cycle types<br />
fp_elt_type_<br />
Element types<br />
7830 9796–013 11–3
Using PCFP with C<br />
fp_st_<br />
fp_ast_<br />
Subtypes for symbolic and omnibus elements<br />
Subtypes for absolute elements<br />
fp_detail_<br />
Levels of information detail that can be returned by a function<br />
fp_on_conflict_<br />
Actions that can be taken by PCFP if an element name-version-type conflict occurs<br />
fp_text_<br />
Element text types<br />
fp_equip_<br />
fp_lff_<br />
File equipment types<br />
Logical file format types<br />
fp_on_end_<br />
Actions that can be taken upon reaching the end of a tape file<br />
fp_min_work_area_<br />
Minimum sizes of the work area required by specific functions<br />
fp_max_work_area_<br />
Maximum sizes of the work area usable by specific functions<br />
11.3. PCFP Data Types<br />
This subsection describes the C constructs used to define the various data types used<br />
by PCFP.<br />
11–4 7830 9796–013
11.3.1. Structure Declarations<br />
Using PCFP with C<br />
The declarations of all structures used by PCFP are in the form of typedef declarations.<br />
Each of these declarations creates a data type that gives the form of the structure, but<br />
does not define the actual structure. The programs that call PCFP must define the actual<br />
structures, using the typedef data types declared in the PCFP include elements.<br />
The following special considerations apply to structures that are returned in the return<br />
area:<br />
• A structure of this type should typically be defined as an array, or as the object of a<br />
pointer that is set to the start of a general return area.<br />
• For many of the return structures, both a short form and a long form exist. Both<br />
forms are declared in the same include element. The form returned by a PCFP<br />
function depends upon what the calling program has specified in the function packet.<br />
• In a few cases, a return structure ends with an array of indeterminate size. Some of<br />
the substructures returned by the _fp_acq_file_info function, defined in fp$rtn$file.h,<br />
are in this category. The C language requires that the typedef declaration of such a<br />
structure be given an exact array bound (instead of an unspecified bound). In the<br />
PCFP include elements, such arrays are declared with an arbitrary size of 10 to<br />
satisfy this requirement. However, the actual size of the array returned by PCFP can<br />
be smaller or larger.<br />
11.3.2. Implementing Generic Data Types<br />
In 2.2, a number of generic data types are described. The following list explains how<br />
these data types are implemented for PCFP in the C language:<br />
• The character generic data type is implemented in C as an array of type char. The<br />
size of the array is equal to the defined length of the string.<br />
When you move a string value shorter than the defined length of the target string,<br />
indicate the actual end of the string with a null character.<br />
A string returned by PCFP can be terminated either with null characters or with<br />
space characters, if it is shorter than the declared size of the string. The usual<br />
C-language convention is to terminate with null characters. To cause this, your<br />
program must set the item gen.null_term_strings to TRUE in the function packet<br />
before calling PCFP.<br />
Note: A string is not null-terminated if its length is equal to the declared size of the<br />
string.<br />
• The integer generic data type is implemented in C as an item of basic type int.<br />
Integer items are further designated as signed or unsigned, depending on the values<br />
they can assume. The size of integer items is indicated by the designators short or<br />
long, or by an actual bit size.<br />
7830 9796–013 11–5
Using PCFP with C<br />
• The condition generic data type is implemented in C as the user-defined data type<br />
fp_condition, which in turn is defined as a 1-bit unsigned integer. Your program<br />
should set condition items only to the defined values of FALSE (0) and TRUE (1).<br />
• Each value-list generic data type is implemented in C by means of a user-defined<br />
typedef. The typedef declaration is defined in one of two ways:<br />
− In cases where all the items declared with the data type occupy 18 bits, the<br />
typedef is defined as an enumeration type. The enum definition specifies the<br />
constant values that the items can be assigned.<br />
− In other cases, the typedef is defined as an unsigned integer type. Following the<br />
typedef definition, a series of #define statements specifies the constant values<br />
that the items can be assigned.<br />
• The date-time generic data type is implemented in C by means of the following<br />
typedef structure:<br />
typedef struct<br />
{ unsigned int year : 18;<br />
unsigned int month : 9;<br />
unsigned int day : 9;<br />
unsigned int milliseconds : 36;<br />
}<br />
fp_date_time_type;<br />
• Some PCFP structures contain items called bit arrays. Logically, these items can be<br />
considered one-dimensional arrays, each item of which has the data type of<br />
condition, and occupies exactly one bit position. This type of structure cannot be<br />
represented directly in C. Instead, a bit-array item is defined as an unsigned integer.<br />
If the bit array cannot fit into a single word (36 bits), it is defined as an array of<br />
unsigned integers. See 11.4.7 for details on how to set the bit items within a bit<br />
array.<br />
11.4. Operating Rules and Coding Sequences<br />
This subsection describes specific rules and coding sequences that must be used in C<br />
programs that call PCFP.<br />
11.4.1. Parameter Definitions<br />
The calling program must define all parameters that it passes to the PCFP functions it<br />
calls, using the typedef data types declared in the PCFP include elements. The<br />
definitions are necessary, since the include elements only declare the forms of the<br />
parameters used by PCFP, not the parameters themselves.<br />
A PCFP parameter can be defined directly, or it can be declared as the object of a<br />
pointer. A parameter can have a storage class of auto, static, or extern. If a parameter<br />
is declared as the object of a pointer, it also could be allocated dynamically.<br />
11–6 7830 9796–013
Using PCFP with C<br />
The following example shows declarations that might be used for the _fp_acq_elt_info<br />
function. The function packet structure is defined in auto storage (the default inside of<br />
functions). The file identifier structure is defined as the object of pointer p_file_id,<br />
perhaps because it will be allocated dynamically. The elt_info array is declared extern,<br />
perhaps because another C routine has allocated the space for this array, and will<br />
process the data placed by PCFP into it. This array is declared large enough to contain<br />
100 occurrences of the long form of the element entry.<br />
fp_acq_elt_info_type acq_elt_pkt;<br />
fp_file_id_type *p_file_id;<br />
extern fp_rtn_elt_info_long_type elt_info [100];<br />
11.4.2. Initializing Input Parameters<br />
Before your program assigns values to specific items of an input parameter, it should<br />
zero-fill the entire parameter. This insures that all defined items in the structure are<br />
initialized to their default values, and that all unassigned areas in the structure contain<br />
zero (as required by PCFP). For most functions, the input parameters that you must<br />
initialize with zero are the function packet and the file identifier(s). It is not necessary to<br />
zero-fill a return area parameter.<br />
You can use the memset function to zero-fill PCFP parameter structures. The following<br />
example shows how to use this function to zero-fill the fp_acq_elt_info_type function<br />
packet defined earlier.<br />
memset ( &acq_elt_pkt, 0, sizeof(fp_acq_elt_info_type) );<br />
Alternatively, if your program declares a PCFP parameter as the object of a pointer, and<br />
allocates it dynamically, you can use the calloc function to zero-fill the parameter at the<br />
time it is allocated. The following example shows allocation and zeroing of a file<br />
identifier structure using the pointer defined earlier.<br />
p_file_id = (fp_file_id_type *)<br />
calloc ( 1, sizeof(fp_file_id_type) );<br />
11.4.3. Assigning Values to Character Strings Within Structures<br />
To assign a character string to a character item, use the strncpy function. Precede the<br />
item name with the structure name and a period. For example, to assign the string<br />
ABCDEFG to item elt_name in the structure acq_elt_pkt, use the following statement:<br />
strncpy (acq_elt_pkt.elt_name,<br />
"ABCDEFG",<br />
sizeof (acq_elt_pkt.elt_name));<br />
Note that this statement causes the value in elt_name to be null-terminated if it is<br />
shorter than the size of elt_name. Also, the value placed into elt_name cannot overflow<br />
into the next item if the value is larger than the size of elt_name.<br />
7830 9796–013 11–7
Using PCFP with C<br />
11.4.4. Work Area Parameter<br />
The last parameter of every PCFP function is the work area parameter. In the current<br />
release of PCFP, the work area is always allocated internally by PCFP, so this parameter<br />
is unused. Always code this parameter as NULL.<br />
Although PCFP always allocates its own work area, the calling program must indicate<br />
how large to make it. The include element for each function defines constants giving the<br />
minimum and maximum work area sizes for that function. The description of each<br />
function in Sections 3 – 10 indicates in general terms the work area needs of that<br />
function. Before your program calls PCFP, you must set the item gen.work_area_size in<br />
the function packet, based on your projected needs for that function.<br />
11.4.5. Calling PCFP<br />
All PCFP functions are true functions, in that they return a value. This returned value is<br />
the ELMS error code generated by the function. (This error code is also returned in the<br />
item error_code in the generic part of the function packet.)<br />
You can code a PCFP function in a C program in any context that allows a function call.<br />
If your program is not coded to examine the function value returned by PCFP, it can<br />
examine the value of the item gen.error_code returned in the function packet instead.<br />
You must code each parameter to each PCFP function as the address of the actual<br />
parameter structure. You can do this by using the & operator, or by specifying an array<br />
name or pointer variable without the & operator.<br />
The following example shows a call to the function acq_elt_info. This example uses the<br />
structures declared in 11.4.1. The first parameter includes the & operator, since the<br />
associated structure is not an array. The second parameter is a pointer variable<br />
containing the location of the parameter structure. The third parameter is an array name<br />
without a subscript. The last parameter is NULL, as explained in 11.4.4.<br />
err_code = _fp_acq_elt_info (&acq_elt_pkt,<br />
p_file_id,<br />
elt_info,<br />
NULL);<br />
11–8 7830 9796–013
11.4.6. Handling Error Conditions<br />
Using PCFP with C<br />
Your program can determine if any warning or error occurred by examining the item<br />
error_class in the function packet. If a warning or error has been returned by the<br />
function, the items error_file, sub_error_code, error_code, and aux_error_code provide<br />
further information you can use to handle the problem. Your program can handle errors<br />
and warnings in a number of ways:<br />
• Your program can print the error code. To do this, your program should take the<br />
remainder of the error code after dividing by 01000000, using the modulus operator:<br />
err_code % 01000000<br />
The number printed in this fashion corresponds to the message numbers listed in<br />
Appendix A.<br />
• Your program can check for specific error code values defined in element<br />
fp$errors.h. This is necessary if your program must take special action for certain<br />
error conditions. Use the entire error code value to make the comparison.<br />
• Your program can call ELMS to print a message appropriate for the error code. Use<br />
the entire error code value as the error_status supplied to ELMS.<br />
11.4.7. Items in a Bit Array<br />
As noted in 11.3.2, an item that is described as a bit array is defined in C as an unsigned<br />
integer, or an array of unsigned integers. To set items in such a bit array, you can use<br />
the left bitwise shift operator
Using PCFP with C<br />
11.4.8. Date-Time Items<br />
You can use the following techniques to handle PCFP date-time items within a C<br />
program.<br />
• To initialize a date-time value to a specific value, set each item within the date-time<br />
structure to the desired value. For example, to set item acq_elt_pkt.max_date_time<br />
to represent March 25, 1991, at 14:35:20, use the following assignment statements:<br />
acq_elt_pkt.max_date_time.year = 1991;<br />
acq_elt_pkt.max_date_time.month = 3;<br />
acq_elt_pkt.max_date_time.day = 25;<br />
acq_elt_pkt.max_date_time.milliseconds =<br />
(14*60*60*1000) + (35*60*1000) + (20*1000);<br />
• To copy a date-time value from one item to another, use a single assignment<br />
statement, as in the following example. (This example assumes that my_date_time<br />
is a variable declared with type fp_date_time_type.)<br />
acq_elt_pkt.max_date_time = my_date_time;<br />
• To compare the values in two date-time items, use the memcmp function. For<br />
example, to determine if the value from my_date_time is less than the value in<br />
acq_elt_pkt.max_date_time, use the following statement fragment:<br />
11.4.9. Return Area<br />
if ( memcmp (&my_date_time,<br />
&acq_elt_pkt.max_date_time,<br />
sizeof (fp_date_time_type)) < 0 )<br />
The following subsections describe information you must consider when you specify a<br />
return area for those PCFP functions that can return a variable amount of information to<br />
the calling program.<br />
11.4.9.1. General Considerations<br />
For your program to receive return entries from a PCFP function that can return such<br />
entries, your program must indicate the following:<br />
• The proper form (short or long) of the data structure that describes the entry<br />
• The form of return entries your program requires<br />
• The location and size of the return area into which PCFP returns these entries<br />
It is important that you keep this information compatible. Failure to keep this information<br />
compatible might cause either PCFP to attempt to return data into unassigned storage or<br />
your program to interpret incorrectly the data PCFP returns.<br />
To indicate the form of the return entry required, set the item info_detail in the function<br />
packet to the required value (fp_detail_short or fp_detail_long).<br />
11–10 7830 9796–013
Using PCFP with C<br />
To specify a return area for PCFP, you must code the address of the return area as the<br />
return area parameter to the function, and you must assign the size of the return area to<br />
the item rtn_info.rtn_area_size in the function packet. You must specify this size in<br />
words.<br />
If you do not want a function to return any data in the return area, simply code the return<br />
area parameter as NULL, and leave rtn_info.rtn_area_size at its initialized value of 0.<br />
You can declare a return area in a number of ways. If your program will receive only a<br />
single type of structure in the return area, you can simply declare an array composed of<br />
that structure type. You must choose the size of the array based upon the maximum<br />
amount of data that you expect PCFP to return, or the maximum amount that you want<br />
your program to process. The following example sets up and uses a return area in this<br />
fashion:<br />
/*Declare the array of element entries to be returned by PCFP.*/<br />
fp_rtn_elt_info_long_type elt_info [100];<br />
.<br />
.<br />
.<br />
/*Set the word size of return area in the function packet.*/<br />
acq_elt_pkt.rtn_info.rtn_area_size = sizeof (elt_info) / 4;<br />
.<br />
.<br />
.<br />
/*Call the PCFP function to retrieve the element entries.*/<br />
_fp_acq_elt_info (&acq_elt_pkt,<br />
&file_id,<br />
elt_info,<br />
NULL);<br />
.<br />
.<br />
.<br />
/*Process the entries of the elt_info array here.*/<br />
for (i=0; i
Using PCFP with C<br />
The following example sets up and uses the same return area for information returned<br />
by both acq_elt_info and acq_om_ep_info:<br />
/*Declare the Return Area*/<br />
long int rtn_area [2000];<br />
/*Declare pointers that refer to the arrays of information<br />
returned by the acq_elt_info and acq_om_ep_info functions.*/<br />
fp_rtn_elt_info_long_type *p_elt;<br />
fp_rtn_om_ep_info_long_type *p_om_ep;<br />
.<br />
.<br />
.<br />
/*Set word size of Return Area in function pkt for acq_elt_info.*/<br />
acq_elt_pkt.rtn_info.rtn_area_size = sizeof (rtn_area) / 4;<br />
.<br />
.<br />
.<br />
/*Set elt_info pointer to the start of rtn_area.*/<br />
p_elt = (fp_rtn_elt_info_long_type *) rtn_area;<br />
.<br />
.<br />
.<br />
/*Call the acq_elt_info function.*/<br />
_fp_acq_elt_info (&acq_elt_pkt,<br />
&file_id,<br />
p_elt,<br />
NULL);<br />
.<br />
.<br />
.<br />
/*Process the element entries in the Return Area here.*/<br />
for (i=0;<br />
i
*Call the acq_om_ep_info function.*/<br />
_fp_acq_om_ep_info (&acq_om_ep_pkt,<br />
&file_id,<br />
p_om_ep,<br />
NULL);<br />
.<br />
.<br />
.<br />
/*Process the OM EP entries in the Return Area here.*/<br />
for (i=0;<br />
ifull_entry_size );<br />
7830 9796–013 11–13
Using PCFP with C<br />
Each file return entry has associated with it a number of substructures that contain the<br />
optional information describing the file. The base entry for the file contains a number of<br />
offset items; these indicate which of the optional substructures is present, and where<br />
they are located. If the offset value for a substructure is zero, that substructure is not<br />
present. If the offset value is nonzero, it gives the offset in words from the start of the<br />
base entry for the file. You can use a code sequence similar to the following to obtain a<br />
pointer to one of these substructures. (In the actual code, replace XXX by the name of<br />
the particular substructure you want.)<br />
fp_rtn_file_info_type *p_file_info;<br />
fp_rtn_file_info_XXX_type *p_XXX_info;<br />
.<br />
.<br />
.<br />
p_XXX_info = (fp_rtn_file_info_XXX_type *)<br />
( (int *) p_file_info + p_file_info->XXX_info_offset );<br />
11.5. Compiling and Linking Programs That Use<br />
PCFP<br />
Compile a C program that calls PCFP exactly as you compile any other C program. No<br />
special statements or options are required. As stated earlier, include elements for PCFP<br />
are contained in file SYS$LIB$*PROC$, and are found automatically by the compiler.<br />
All linking required for a C program to call PCFP is handled transparently by the Linking<br />
System. This is true whether you use dynamic linking or static linking for your program.<br />
The file that contains the PCFP executable code is in the default link search chain, so<br />
that the Linking System can always resolve references from your program to PCFP<br />
without any special statements or options.<br />
11.6. <strong>Programming</strong> Examples<br />
This subsection contains examples of three C programs each calling a different PCFP<br />
function. These examples correspond to those in 1.3.<br />
11–14 7830 9796–013
11.6.1. Calling PCFP to Delete a File<br />
Using PCFP with C<br />
This example shows a C program that calls the _fp_delete_file function to delete the file<br />
A*B.<br />
/* EXAMPLE1 */<br />
/* Delete file A*B. */<br />
#include <br />
#include <br />
#include <br />
#include <br />
#include <br />
#include <br />
#include <br />
main()<br />
{<br />
/* Define the function packet */<br />
fp_delete_file_type df_pkt;<br />
/* Define the file identifier structure. */<br />
fp_file_id_type file_id;<br />
/* Zero-fill the function packet. */<br />
memset (&df_pkt, 0, sizeof (fp_delete_file_type));<br />
/* Set items in the function packet. */<br />
df_pkt.gen.interface_level = fp_interface_level_1;<br />
df_pkt.gen.null_term_strings = TRUE;<br />
df_pkt.gen.work_area_size = fp_max_work_area_delete_file;<br />
/* Zero-fill the file identifier. */<br />
memset (&file_id, 0, sizeof (fp_file_id_type));<br />
/* Set items in the file id. */<br />
file_id.interface_level = fp_interface_level_1;<br />
strncpy (file_id.qualifier,<br />
"A",<br />
sizeof (file_id.qualifier));<br />
strncpy (file_id.filename,<br />
"B",<br />
sizeof (file_id.filename));<br />
_fp_delete_file (&df_pkt,<br />
&file_id,<br />
NULL);<br />
if ( df_pkt.gen.error_class != fp_error_class_none )<br />
printf ("File was not deleted - error code: % u\n",<br />
df_pkt.gen.error_code % 01000000);<br />
}<br />
7830 9796–013 11–15
Using PCFP with C<br />
11.6.2. Calling PCFP to Copy a File<br />
This example shows a C program that calls the _fp_copy_raf_raf function to copy the<br />
contents of mass storage file A*B(2) to the mass storage file with internal name FILE2.<br />
/* EXAMPLE2 */<br />
/* Copy mass storage file A*B(2) into mass storage file FILE2. */<br />
#include <br />
#include <br />
#include <br />
#include <br />
#include <br />
#include <br />
#include <br />
main()<br />
{<br />
/* Define the function packet */<br />
fp_copy_raf_raf_type cpy_pkt;<br />
/* Define the file identifier structures. */<br />
fp_file_id_type source_file_id;<br />
fp_file_id_type dest_file_id;<br />
/* Zero-fill the function packet. */<br />
memset (&cpy_pkt, 0, sizeof (fp_copy_raf_raf_type));<br />
/* Set items in the function packet. */<br />
cpy_pkt.gen.interface_level = fp_interface_level_1;<br />
cpy_pkt.gen.null_term_strings = TRUE;<br />
cpy_pkt.gen.work_area_size = fp_max_work_area_copy_raf_raf;<br />
/* Zero-fill the source file identifier. */<br />
memset (&source_file_id, 0, sizeof (fp_file_id_type));<br />
/* Set items in the source file id. */<br />
source_file_id.interface_level = fp_interface_level_1;<br />
strncpy (source_file_id.qualifier,<br />
"A",<br />
sizeof (source_file_id.qualifier));<br />
strncpy (source_file_id.filename,<br />
"B",<br />
sizeof (source_file_id.filename));<br />
source_file_id.f_cycle_type = fp_cycle_abs;<br />
source_file_id.f_cycle = 2;<br />
/* Zero-fill the destination file identifier. */<br />
memset (&dest_file_id, 0, sizeof (fp_file_id_type));<br />
/* Set items in the destination file id. */<br />
dest_file_id.interface_level = fp_interface_level_1;<br />
strncpy (dest_file_id.filename,<br />
"FILE2",<br />
sizeof (dest_file_id.filename));<br />
11–16 7830 9796–013
_fp_copy_raf_raf (&cpy_pkt,<br />
&source_file_id,<br />
&dest_file_id,<br />
NULL);<br />
if ( cpy_pkt.gen.error_class != fp_error_class_none )<br />
printf ("File was not copied - error code: % u\n",<br />
cpy_pkt.gen.error_code % 01000000);<br />
else<br />
printf ("Successful copy - tracks copied: % u\n",<br />
cpy_pkt.amount_copied/1792);<br />
}<br />
Using PCFP with C<br />
11.6.3. Calling PCFP to Acquire Element Information from a<br />
Program File<br />
This example shows a C program that calls the _fp_acq_elt_info function to acquire all<br />
information about the symbolic elements in program file A*B. This example prints the<br />
name, version, subtype, and sequence number of each element for which PCFP<br />
returned information.<br />
/* EXAMPLE3 */<br />
/* Print name, version, subtype, and sequence number<br />
for all symbolic elements in file A*B. */<br />
#include <br />
#include <br />
#include <br />
#include <br />
#include <br />
#include <br />
#include <br />
#include <br />
#include <br />
main()<br />
{<br />
/* Define the function packet */<br />
fp_acq_elt_info_type acq_pkt;<br />
/* Define the file identifier structure. */<br />
fp_file_id_type file_id;<br />
/* Define an array to contain the information returned. */<br />
fp_rtn_elt_info_long_type elt_info [125];<br />
int i; /* Array index */<br />
/* Zero-fill the function packet. */<br />
memset (&acq_pkt, 0, sizeof (fp_acq_elt_info_type));<br />
7830 9796–013 11–17
Using PCFP with C<br />
/* Set items in the function packet. */<br />
acq_pkt.gen.interface_level = fp_interface_level_1;<br />
acq_pkt.gen.null_term_strings = TRUE;<br />
acq_pkt.gen.work_area_size = fp_max_work_area_acq_elt_info;<br />
acq_pkt.rtn_info.rtn_area_size = sizeof (elt_info) / 4;<br />
acq_pkt.sym_type = TRUE;<br />
acq_pkt.info_detail = fp_detail_long;<br />
/* Zero-fill the file identifier. */<br />
memset (&file_id, 0, sizeof (fp_file_id_type));<br />
/* Set items in the file id. */<br />
file_id.interface_level = fp_interface_level_1;<br />
strncpy (file_id.qualifier,<br />
"A",<br />
sizeof (file_id.qualifier));<br />
strncpy (file_id.filename,<br />
"B",<br />
sizeof (file_id.filename));<br />
_fp_acq_elt_info (&acq_pkt,<br />
&file_id,<br />
elt_info,<br />
NULL);<br />
if ( acq_pkt.gen.error_class != fp_error_class_none )<br />
printf ("Acq_Elt_Info not successful - error code: % u\n",<br />
acq_pkt.gen.error_code > 01000000);<br />
else<br />
{<br />
printf ("Number of elements selected: % u\n",<br />
acq_pkt.num_selected);<br />
};<br />
}<br />
for ( i = 0;<br />
i < acq_pkt.rtn_info.num_entries_in_rtn_area;<br />
i++ )<br />
{<br />
printf ("%-12.12s / %-12.12s %.4s % u\n",<br />
elt_info[i].elt_name,<br />
elt_info[i].elt_version,<br />
elt_info[i].elt_subtype_name,<br />
elt_info[i].seq_num);<br />
};<br />
11–18 7830 9796–013
Section 12<br />
Using PCFP with COBOL<br />
This section contains information about using PCFP with programs written in COBOL.<br />
12.1. Copy Considerations<br />
All PCFP copy elements used by COBOL programs have a version name of COB, and all<br />
have names beginning with the characters FP$. The PDP processor makes COBOL<br />
procedures from these copy elements. These COBOL procedures are all contained in<br />
the file SYS$LIB$*PROC$, which is searched automatically by the UCOB compiler.<br />
Thus, it is not necessary to code the file name in the COPY statement. The<br />
recommended form for including COBOL PCFP definition procedures is<br />
COPY FP-xxxxxxxxx.<br />
where xxxxxxxxx represents the specific part of the procedure name.<br />
Include the following PCFP COBOL procedures in most or all COBOL programs that call<br />
PCFP:<br />
• FP-DEFS.<br />
This COBOL procedure contains the definition of constants that are used by all PCFP<br />
subroutines. You must copy this COBOL procedure in every program that calls<br />
PCFP, and you must include it before any other PCFP procedures in the<br />
WORKING-STORAGE SECTION as follows:<br />
WORKING-STORAGE SECTION.<br />
COPY FP-Defs.<br />
• FP-ERRORS.<br />
This COBOL procedure contains constant definitions of error codes that PCFP can<br />
return. You must copy this procedure only if your program refers to specific error<br />
codes by their defined names.<br />
COPY FP-Errors.<br />
7830 9796–013 12–1
Using PCFP with COBOL<br />
• FP-FILE-ID.<br />
This COBOL procedure contains the definition of the file identifier record, which is<br />
used as a parameter by most PCFP subroutines. You must copy this COBOL<br />
procedure into any program that calls PCFP subroutines that require a source file<br />
identifier parameter.<br />
COPY FP-File-Id.<br />
If the PCFP subroutine also requires a destination file identifier, you must copy this<br />
COBOL procedure a second time, using the REPLACING clause as follows:<br />
COPY FP-File-Id REPLACING FP-File-Id BY FP-Dest-File-Id.<br />
• FP-fffffffff.<br />
This name refers to each of the COBOL procedures that contains the definition of a<br />
specific subroutine packet. fffffffff is the subroutine name as given in Sections 3 –<br />
10. Exactly one of these COBOL procedures exists for each PCFP subroutine. Each<br />
of these COBOL procedures also contains the work area requirements for the<br />
subroutine. You must copy one of these COBOL procedures into your program for<br />
each different PCFP subroutine that it calls. Do not copy COBOL procedures for any<br />
PCFP subroutine not called by the program.<br />
To define the subroutine packet for the FP-Acq-Elt-Info subroutine, use the following<br />
statement:<br />
COPY FP-Acq-Elt-Info.<br />
• FP-RTN-rrrrr.<br />
This name refers to the COBOL procedures that contain the definitions of the<br />
repeating records that certain PCFP subroutines return. One of these procedures<br />
exists for each unique record that PCFP can return. rrrrr is a mnemonic for the<br />
record defined by the procedure. Include in your program only those procedures<br />
used by the PCFP subroutines that your program calls. The subroutine descriptions<br />
in Sections 3 – 10 state what return records are returned by each PCFP subroutine.<br />
Set the maximum number of return records expected by replacing a variable in the<br />
return procedure with the number of records desired. To set the maximum number<br />
of return records, use the following clause:<br />
REPLACING xxxx-Array-Size BY yyy<br />
where xxxx is the name of the array and yyy is the maximum number of return<br />
records expected.<br />
For many of the return records, both a short and a long form exist. Each form is<br />
defined in a separate procedure. The form returned by a PCFP subroutine depends<br />
upon what your calling program has specified as Info-Detail in the subroutine packet.<br />
To define an array of 100 short return records for the FP-Acq-Elt-Info subroutine, use<br />
the following statement:<br />
COPY FP-Rtn-Elt-Info-Short REPLACING Elt-Array-Size BY 100.<br />
12–2 7830 9796–013
• CALL-FP-fffffffff<br />
Using PCFP with COBOL<br />
This name refers to each of the COBOL procedures that contains a CALL to a<br />
specific PCFP subroutine. fffffffff is the function name as given in Sections 3 – 10.<br />
At least one of these CALL procedures exists for each PCFP subroutine. If a PCFP<br />
subroutine returns records, at least two of these COBOL CALL procedures exist:<br />
one requesting the long form and one the short form of the return records.<br />
To CALL the PCFP subroutine FP-Acq-Elt-Info to obtain the short form of the return<br />
record, use the following statement:<br />
COPY Call-FP-Acq-Elt-Info-Short.<br />
This CALL procedure generates the following COBOL statement:<br />
CALL 'fp_acq_elt_info' USING FP-ACQ-ELT-INFO,<br />
FP-FILE-ID,<br />
FP-RTN-ELT-INFO-SHORT.<br />
You can also code the subroutine CALL directly. These CALL procedures are<br />
provided only for convenience.<br />
Note: These CALL procedures are copied into the PROCEDURE DIVISION of your<br />
program, unlike the other procedures that are copied into the DATA DIVISION.<br />
12.2. Naming Conventions<br />
For COBOL programs, all globally defined names begin with the characters FP-. In<br />
programs that call PCFP, avoid defining names starting with these characters so that<br />
there is no conflict between the names you define and the names defined for PCFP. As<br />
with all names in COBOL, there is no distinction between uppercase and lowercase<br />
letters.<br />
12.2.1. Subroutine Names<br />
For COBOL programs, the names of all PCFP subroutines are identical to the function<br />
names given in Sections 3 – 10, except that the COBOL names use a hyphen ( - ) instead<br />
of an underscore ( _ ), and are prefixed with the letters FP-.<br />
The COBOL procedures supplied with PCFP and the examples in this section follow the<br />
convention that subroutine names appear in all lowercase letters.<br />
12.2.2. Item Names<br />
For COBOL programs, the names of all items within records are exactly the same as<br />
shown in Sections 2 – 10, except that all COBOL names use a hyphen ( - ) instead of an<br />
underscore ( _ ). Item names do not have the FP- prefix, because each item name can<br />
be qualified by the record that contains it. Hence, item names do not need to be globally<br />
unique.<br />
7830 9796–013 12–3
Using PCFP with COBOL<br />
The COBOL procedures supplied with PCFP and the examples in this section follow the<br />
convention that item names and the parts within them (alphabetic pieces separated by a<br />
hyphen) begin with an initial capital letter. Acronyms frequently used in this document<br />
appear in all capital letters, for example, RAF, SAF, and FP.<br />
Exceptions to the above rules occur when names of items conflict with COBOL reserved<br />
words, as follows:<br />
• PF is a COBOL reserved word. In the descriptions of the following items, the<br />
COBOL name for standard program file (spf ) is used instead of the documented<br />
name PF:<br />
− INIT_PROGRAM_FILE (4.1.2)<br />
− PROGRAM_FILE_TYPE (6.1.2)<br />
− INIT_DEST_FILE (7.1.2, 7.3.2, and 7.5.2)<br />
• TAPE is a COBOL reserved word. In 3.1.4.1 for the EQUIP_TYPE item, the COBOL<br />
name “tape-storage” is used instead of the documented name TAPE.<br />
12.2.3. Names of Constants<br />
The names of constants are implemented in COBOL in two different ways.<br />
• Constant names that are used by multiple PCFP subroutines are defined in<br />
procedure FP-DEFS. All of these PCFP constants start with the prefix FP-. For those<br />
constants that are part of a list of constants, the characters FP- are followed by a<br />
short abbreviation that identifies the list to which the constant belongs. This naming<br />
scheme assures the global uniqueness of all constant names.<br />
The following prefixes are used for those constants that are part of a list of<br />
constants:<br />
fp-err- PCFP error codes<br />
fp-warn- PCFP warning codes<br />
fp-ept- Object module entry point types<br />
fp-elt-subtype- Subtypes for symbolic, omnibus, and absolute elements<br />
fp-min-work-area- Minimum size of the work area required by specific subroutines<br />
fp-max-work-area- Maximum size of the work area usable by specific subroutines<br />
• Constant names that are associated with only a single record usually are defined in<br />
the COBOL procedure that defines that record. These constants are implemented in<br />
COBOL with 88 statements. Each 88 statement value list is unique to the data item<br />
that contains it. Therefore, these constant names do not start with the prefix FP-.<br />
The COBOL procedures supplied with PCFP and the examples in this section follow the<br />
convention that constant names appear in all lowercase letters.<br />
12.3. PCFP Data Types<br />
This subsection describes the COBOL constructs used to define the various data types<br />
used by PCFP.<br />
12–4 7830 9796–013
12.3.1. Record Definitions<br />
Using PCFP with COBOL<br />
The definitions of all parameters used to call PCFP are in the form of COBOL records.<br />
The programs that call PCFP subroutines must declare storage for the parameter records<br />
by copying the necessary COBOL procedures into the WORKING-STORAGE SECTION<br />
as shown in the COBOL examples in 12.6.<br />
Special consideration applies to records that are returned by the Acq-File-Info and<br />
Acq-File-List subroutines. A file can have any number of use names and volume-ids. For<br />
PCFP to return all of these for any file requires a return record of variable size. Because<br />
this is difficult to accomplish in COBOL, the structure PCFP uses to return file<br />
information in COBOL contains exactly three occurrences of these items. In those cases<br />
where a file has more than three use names, PCFP returns only three, but places the<br />
total number that actually exist in item NUM_USE_NAMES. Similarly, PCFP returns no<br />
more than three volume-ids for a file, but places the true count in item NUM_VOLS.<br />
12.3.2. Implementing Generic Data Types<br />
In 2.2, a number of generic data types are described. The following list explains how<br />
these data types are implemented for the COBOL language.<br />
• The character generic data type is implemented in COBOL as PIC X.<br />
02 Elt-Name PIC X(12) USAGE DISPLAY.<br />
• The integer generic data type is implemented in COBOL as PIC 1. Integer items are<br />
unsigned, unless they are designated signed with an S in the PIC.<br />
02 Num-Entries PIC 1(18) USAGE BINARY-1.<br />
• The condition generic data type is implemented in COBOL as PIC 1(1). Condition<br />
items can be assigned only the values of 1 (signifying TRUE) and 0 (signifying<br />
FALSE).<br />
02 Abs-Type PIC 1(1) USAGE BINARY-1.<br />
• Some records contain items called bit arrays. Logically, these items can be<br />
considered one-dimensional arrays, each item of which occupies exactly one bit<br />
position.<br />
02 Abs-Subtype PIC 1(1) USAGE BINARY-1<br />
OCCURS 18 TIMES.<br />
• The value-list generic data type is implemented in COBOL by 88 statements.<br />
02 Info-Detail PIC 1(18) USAGE BINARY-1.<br />
88 short VALUE 0.<br />
88 long VALUE 1.<br />
• The date-time generic data type is implemented in COBOL by the following COBOL<br />
structure:<br />
02 Date-Time.<br />
03 Year PIC 1(18) USAGE BINARY-1.<br />
7830 9796–013 12–5
Using PCFP with COBOL<br />
03 Month PIC 1(9) USAGE BINARY-1.<br />
03 Day-of-Month PIC 1(9) USAGE BINARY-1.<br />
03 Milliseconds PIC 1(36) USAGE BINARY-1.<br />
12.4. Operating Rules and Coding Sequences<br />
This subsection describes specific rules and coding sequences that must be used in<br />
COBOL programs that call PCFP subroutines.<br />
12.4.1. Initializing Input Parameters<br />
Before a program assigns values to specific items of an input parameter record, it must<br />
zero-fill the entire record. This ensures that all defined items in the record are initialized<br />
to their default values, and that all filler areas in the record contain zero (as required by<br />
PCFP). For most subroutines, the input parameters that the calling program must<br />
initialize with zero are the subroutine packet and the file identifier record(s). It is not<br />
necessary to zero-fill a return area record.<br />
Use the statement MOVE LOW-VALUES to zero-fill PCFP parameter records. Each<br />
PCFP subroutine COPY procedure provides guidance for zero-filling the record.<br />
The following example shows how to use the MOVE statement to zero-fill the<br />
FP-Acq-Elt-Info subroutine packet:<br />
MOVE LOW-VALUES TO FP-Acq-Elt-Info.<br />
12.4.2. Work Area Specification<br />
The work area is always allocated internally by PCFP, so this parameter is not used;<br />
therefore, do not code this parameter in the COBOL program.<br />
Although PCFP always allocates its own work area, the calling program must indicate<br />
how large to make it. The COPY procedure for each subroutine defines constants giving<br />
the minimum and maximum work area sizes for that subroutine. The description of each<br />
subroutine in Sections 3 – 10 indicates in general the work area needs of that subroutine.<br />
Before your program calls PCFP, it must set the item Work-Area-Size in the subroutine<br />
packet, based on your projected needs for that subroutine.<br />
12–6 7830 9796–013
12.4.3. Setting Items in a Bit Array<br />
Using PCFP with COBOL<br />
As noted in 12.3.2, an item that is described as a bit array is defined in COBOL as an<br />
array of PIC 1(1) USAGE BINARY-1 items.<br />
To see an example of a bit array that uses the item Abs-Subtype-Array in the<br />
FP-Acq-Elt-Info subroutine packet, execute the example in 12.6.3. You may use a<br />
constant in the Abs-Subtype-List as an index to set a required bit in the Abs-Subtype bit<br />
array. However, you must add one (1) to these constants to use them as indexes. As an<br />
example, the following statement sets the appropriate bit of Abs-Subtype to acquire<br />
information only on object module (OM) absolute subtypes:<br />
MOVE 1 TO Abs-Subtype ( fp-elt-subtype-om + 1 ).<br />
You can use statements of this nature successively to set any number of bits within the<br />
same bit array.<br />
Note that Abs-Subtype only affects the selection of absolute elements. Also, if your<br />
program sets no items in this array, PCFP selects absolute elements regardless of<br />
subtype.<br />
12.4.4. Handling Date-Time Items<br />
The following techniques can be used to handle PCFP date-time items within a COBOL<br />
program.<br />
• To initialize a date-time item to a specific value, set each item within the date-time<br />
group item to the desired value. For example, to set item Max-Date-Time of<br />
FP-Acq-Elt-Info to represent March 25, 1991, at 14:35:20, use the following<br />
assignment statements:<br />
MOVE 1991 TO Year OF Max-Date-Time.<br />
MOVE 3 TO Month OF Max-Date-Time.<br />
MOVE 25 TO Day-of-Month OF Max-Date-Time.<br />
COMPUTE Milliseconds OF Max-Date-Time =<br />
(14 * 60 * 60 * 1000) +<br />
(35 * 60 * 1000) +<br />
(20 * 1000).<br />
• To compare the values in two date-time items, compare the date-time items as<br />
group items. For example, to determine if the value from Your-Date-Time is less<br />
than the value in Max-Date-Time, use the following statement:<br />
IF Your-Date-Time < Max-Date-Time<br />
7830 9796–013 12–7
Using PCFP with COBOL<br />
12.4.5. Handling Error Conditions<br />
The status generated by the call to a PCFP subroutine is returned in the subroutine<br />
packet. If the Error-Class equals none, the subroutine call was successful. If Error-Class<br />
does not equal none, a warning or error has occurred during the subroutine call and the<br />
items Error-Class, Error-File, Sub-Error-Code, Error-Code, and Aux-Error-Code provide<br />
information that can be used to determine the problem.<br />
Your program can print the Msg-Code portion of the error code. The number printed in<br />
this fashion corresponds to the message numbers listed in Appendix A.<br />
Your program can check for specific error code values defined in procedure FP-ERRORS.<br />
This is necessary if your program must take special action for certain error conditions.<br />
Use the entire error code value to make the comparison.<br />
12.4.6. Handling the Return Area Parameter<br />
The Return Area is used by those PCFP subroutines that can return a variable amount of<br />
information to the calling program.<br />
If you do not want a subroutine to return any data in the Return Area, leave the item<br />
Rtn-Area-Size in the subroutine packet at its initialized value (0). If you use the supplied<br />
CALL subroutine procedure, you must still include a copy of the return area record in the<br />
WORKING-STORAGE SECTION, because the CALL uses the standard return record as a<br />
parameter. If you are not using the supplied CALL subroutine procedure, you can code<br />
the Return-Area-Parameter with a zero as follows:<br />
CALL 'fp_copy_elt' USING FP-COPY-ELT,<br />
FP-FILE-ID,<br />
FP-DEST-FILE-ID,<br />
0.<br />
If you want a PCFP subroutine to return records in the return area, you must do the<br />
following:<br />
• Make sure the subroutine is designed to return records. The subroutine descriptions<br />
in Sections 3 – 10 state whether or not the subroutine returns any records.<br />
• COPY the correct return area procedure into your program, specifying the maximum<br />
expected number of return records as the array size. You must choose the size of<br />
the array (number of records) based upon the maximum number of records that you<br />
expect PCFP to return, or the maximum number you want your program to process.<br />
The following statement allows for 100 long element records to be returned by the<br />
FP-Acq-Elt-Info subroutine procedure.<br />
COPY FP-Rtn-Elt-Info-Long REPLACING Elt-Array-Size BY 100.<br />
12–8 7830 9796–013
Using PCFP with COBOL<br />
• Specify the Rtn-Area-Size in the subroutine packet. You must specify this size in<br />
words. Each procedure that describes a return record contains a constant describing<br />
the length (in words) of that record, to aid in the calculation of the Rtn-Area-Size. As<br />
an example, to calculate the Rtn-Area-Size for 100 long return element records to be<br />
returned by the FP-Acq-Elt-Info subroutine, use the following statement:<br />
MULTIPLY 100 BY fp-rtn-elt-info-long-size GIVING Rtn-Area-Size.<br />
• Indicate in the subroutine packet the form of the return record you want: short or<br />
long. When your program initialized the subroutine packet, Info-Detail is set to its<br />
default value of short. To obtain the long form of the return record, set Info-Detail to<br />
long with the following statement:<br />
SET long OF Info-Detail TO TRUE.<br />
• COPY the appropriate PCFP CALL procedure that returns the matching form of the<br />
return record (short or long), so that the information returned can be used by the<br />
COBOL program. For example, use the following CALL procedure to call the<br />
FP-Acq-Elt-Info subroutine procedure to obtain the long form of element records in<br />
the return area:<br />
COPY Call-FP-Acq-Elt-Info-Long.<br />
Remember that you must keep the number of return records, Rtn-Area-Size, Info-Detail,<br />
and the CALL procedure compatible. If they are not compatible, either PCFP might<br />
attempt to return data into unassigned storage or your program might not correctly<br />
interpret the data PCFP does return.<br />
12.5. Compiling and Linking Programs That Use<br />
PCFP<br />
Compile a COBOL program that calls PCFP exactly as you compile any other COBOL<br />
program. No special statements or options are required. As stated earlier, COPY<br />
procedures for PCFP are contained in file SYS$LIB$*PROC$, and are found automatically<br />
by the compiler.<br />
All linking required for a COBOL program to call PCFP is handled transparently by the<br />
Linking System. This is true whether you use dynamic linking or static linking for your<br />
program. The file that contains the PCFP executable code is in the default link search<br />
chain, so that the Linking System can always resolve references from your program to<br />
PCFP without any special statements or options.<br />
12.6. <strong>Programming</strong> Examples<br />
This subsection contains examples of three COBOL programs, each calling a different<br />
PCFP function. These examples correspond to those in 1.3.<br />
7830 9796–013 12–9
Using PCFP with COBOL<br />
12.6.1. Calling PCFP to Delete a File<br />
This example shows a COBOL program that calls the FP-Delete-File subroutine to delete<br />
the file A*B.<br />
IDENTIFICATION DIVISION.<br />
PROGRAM-ID. example-1.<br />
ENVIRONMENT DIVISION.<br />
CONFIGURATION SECTION.<br />
SOURCE-COMPUTER. UNISYS-2200-11.<br />
OBJECT-COMPUTER. UNISYS-2200-11.<br />
SPECIAL-NAMES. PRINTER IS PRINTER.<br />
DATA DIVISION.<br />
WORKING-STORAGE SECTION.<br />
*<br />
COPY FP-Defs.<br />
COPY FP-Delete-File.<br />
COPY FP-File-Id.<br />
*<br />
PROCEDURE DIVISION.<br />
START-OF-PROGRAM.<br />
* Set up Delete File Subroutine Packet<br />
MOVE LOW-VALUES TO FP-Delete-File.<br />
MOVE fp-interface-level-1 TO Interface-Level<br />
OF FP-Delete-File.<br />
MOVE fp-max-work-area-delete-file TO Work-Area-Size<br />
OF FP-Delete-File.<br />
* Set up Source File Identifier<br />
*<br />
MOVE LOW-VALUES TO FP-File-Id.<br />
MOVE fp-interface-level-1 TO Interface-Level<br />
OF FP-File-Id.<br />
MOVE 'A' TO Qualifier OF FP-File-Id.<br />
MOVE 'B' TO Filename OF FP-File-Id.<br />
* Call Delete File - PCFP Subroutine.<br />
COPY Call-FP-Delete-File.<br />
* Check if the results are negative.<br />
IF NOT none OF Error-Class<br />
DISPLAY 'File was not deleted - Error Code: '<br />
Msg-Code OF Error-Code UPON PRINTER<br />
END-IF.<br />
12–10 7830 9796–013
END<br />
*<br />
12.6.2. Calling PCFP to Copy a File<br />
Using PCFP with COBOL<br />
This example shows a COBOL program that calls the FP_Copy_RAF_RAF subroutine to<br />
copy the contents of mass storage file A*B(2) to the mass storage file with an internal<br />
name of FILE2.<br />
IDENTIFICATION DIVISION.<br />
PROGRAM-ID. example-2.<br />
ENVIRONMENT DIVISION.<br />
CONFIGURATION SECTION.<br />
SOURCE-COMPUTER. UNISYS-2200-11.<br />
OBJECT-COMPUTER. UNISYS-2200-11.<br />
SPECIAL-NAMES. PRINTER IS PRINTER.<br />
DATA DIVISION.<br />
WORKING-STORAGE SECTION.<br />
*<br />
COPY FP-Defs.<br />
COPY FP-Copy-RAF-RAF.<br />
COPY FP-File-Id.<br />
COPY FP-File-Id REPLACING FP-File-Id BY FP-Dest-File-Id.<br />
*<br />
PROCEDURE DIVISION.<br />
START-OF-PROGRAM.<br />
* Set up FP-Copy-RAF-RAF Subroutine Packet<br />
MOVE LOW-VALUES TO FP-Copy-RAF-RAF.<br />
MOVE fp-interface-level-1 TO Interface-Level<br />
OF FP-Copy-RAF-RAF.<br />
MOVE fp-max-work-area-copy-raf-raf TO Work-Area-Size<br />
OF FP-Copy-RAF-RAF.<br />
* Set up Source File Identifier<br />
*<br />
MOVE LOW-VALUES TO FP-File-Id.<br />
MOVE fp-interface-level-1 TO Interface-Level<br />
OF FP-File-Id.<br />
MOVE 'A' TO Qualifier OF FP-File-Id.<br />
MOVE 'B' TO Filename OF FP-File-Id.<br />
SET abs OF FP-File-Id TO TRUE.<br />
MOVE 2 TO F-Cycle OF FP-File-Id.<br />
* Set up Destination File Identifier<br />
MOVE LOW-VALUES TO FP-Dest-File-Id.<br />
7830 9796–013 12–11
Using PCFP with COBOL<br />
*<br />
MOVE fp-interface-level-1 TO Interface-Level<br />
OF FP-Dest-File-Id.<br />
MOVE 'FILE2' TO Filename OF FP-Dest-File-Id.<br />
12–12 7830 9796–013
END<br />
* Call Copy-RAF-RAF - PCFP Subroutine.<br />
COPY Call-FP-Copy-RAF-RAF.<br />
* Check if the results are negative.<br />
IF NOT none OF Error-Class<br />
DISPLAY 'File was not copied - Error-Code: '<br />
Msg-Code OF Error-Code UPON PRINTER<br />
ELSE<br />
* Print out amount copied in tracks.<br />
*<br />
DIVIDE Amount-Copied BY 1792 GIVING Amount-Copied<br />
DISPLAY 'Successful copy - Tracks-Copied: '<br />
Amount-Copied UPON PRINTER<br />
END-IF.<br />
Using PCFP with COBOL<br />
7830 9796–013 12–13
Using PCFP with COBOL<br />
12.6.3. Calling PCFP to Acquire Element Information from a<br />
Program File<br />
This example shows a COBOL program that calls the FP_Acq_Elt_Info subroutine to<br />
acquire all information about the symbolic elements in program file A*B. This example<br />
prints the name, version, subtype, and sequence number of each element selected by<br />
PCFP.<br />
IDENTIFICATION DIVISION.<br />
PROGRAM-ID. example-3.<br />
ENVIRONMENT DIVISION.<br />
CONFIGURATION SECTION.<br />
SOURCE-COMPUTER. UNISYS-2200-11.<br />
OBJECT-COMPUTER. UNISYS-2200-11.<br />
SPECIAL-NAMES. PRINTER IS PRINTER.<br />
DATA DIVISION.<br />
WORKING-STORAGE SECTION.<br />
*<br />
COPY FP-Defs.<br />
COPY FP-Acq-Elt-Info.<br />
COPY FP-File-Id.<br />
COPY FP-Rtn-Elt-Info-Long REPLACING Elt-Array-Size BY 100.<br />
01 SS PIC 9(10) USAGE BINARY.<br />
*<br />
PROCEDURE DIVISION.<br />
START-OF-PROGRAM.<br />
* Set up Acq-Elt-Info Subroutine Packet.<br />
MOVE LOW-VALUES TO FP-Acq-Elt-Info.<br />
MOVE fp-interface-level-1 TO Interface-Level<br />
OF FP-Acq-Elt-Info.<br />
MOVE fp-max-work-area-acq-elt-info TO Work-Area-Size.<br />
MULTIPLY fp-rtn-elt-info-long-size BY 100<br />
GIVING Return-Area-Size.<br />
* Set up File Identifier Packet.<br />
MOVE LOW-VALUES TO FP-File-Id.<br />
MOVE fp-interface-level-1 TO Interface-Level<br />
OF FP-File-Id.<br />
MOVE 'A' TO Qualifier OF FP-File-Id.<br />
MOVE 'B' TO Filename OF FP-File-Id.<br />
* Set Symbolic Type only<br />
MOVE 1 TO Sym-Type OF FP-Acq-Elt-Info.<br />
12–14 7830 9796–013
END<br />
Using PCFP with COBOL<br />
* Indicate that the long form of return information is desired.<br />
SET long OF FP-Acq-Elt-Info TO TRUE.<br />
* Call Acquire Element Information PCFP Function.<br />
COPY Call-FP-Acq-Elt-Info-Long.<br />
* Check for negative results.<br />
IF NOT none OF Error-Class<br />
DISPLAY 'Acq-Elt-Info not successful - Error-Code: '<br />
Msg-Code OF Error-Code UPON PRINTER<br />
ELSE<br />
* Display number of elements selected by PCFP.<br />
DISPLAY 'Number of Elements Selected: '<br />
Num-Selected UPON PRINTER<br />
* Print the Element Items returned by PCFP.<br />
*<br />
PERFORM VARYING SS FROM 1 BY 1 UNTIL SS ><br />
Num-Entries-in-Rtn-Area<br />
DISPLAY<br />
Elt-Name OF FP-Rtn-Elt-Info-Long (SS) '/'<br />
Elt-Version OF FP-Rtn-Elt-Info-Long (SS) ' '<br />
Elt-Subtype-Name OF FP-Rtn-Elt-Info-Long (SS) ' '<br />
Seq-Num (SS) UPON PRINTER<br />
END-PERFORM<br />
END-IF.<br />
7830 9796–013 12–15
Using PCFP with COBOL<br />
12–16 7830 9796–013
Section 13<br />
Using PCFP with FORTRAN<br />
This section contains information about using PCFP with programs written in FORTRAN.<br />
Throughout this section, the term procedure is used to mean an INCLUDE procedure.<br />
13.1. INCLUDE Element/Procedure Considerations<br />
A number of FORTRAN procedures exist to assist a FORTRAN programmer in calling<br />
PCFP. Two of these procedures define constants and the remaining procedures define<br />
the function packets, file identifier packets, and repeating return information. These<br />
procedure names begin with the character sequence fp$. They exist in the file<br />
SYS$LIB$*PROC$, which is searched automatically by the UFTN compiler. These<br />
procedures exist in elements that, in most cases, have the same names as the<br />
procedure names. Slight differences exist between the procedure and element names<br />
for those procedures that define repeating return information. All PCFP include<br />
elements used by FORTRAN programs have a version name of FTN. Each of these<br />
general procedures is described in the following list:<br />
• FP$DEFS<br />
This procedure contains the names and the associated values for constants used in<br />
assigning values to<br />
− Value-list integer items within the packets presented to PCFP<br />
− The entries returned by PCFP<br />
You must include this procedure in every FORTRAN program that calls PCFP. When<br />
analyzing or inserting value-list items in any of the packets or in information returned<br />
by the PCFP, you are encouraged to use the symbolic names defined in this<br />
procedure.<br />
• FP$ERRORS<br />
This procedure defines the names and associated values of error codes returned by<br />
PCFP. You are encouraged to include this procedure within your program and to use<br />
the symbolic names defined in this procedure in any program that performs specific<br />
analysis of error codes returned by PCFP.<br />
• FP$SFILE$ID<br />
This procedure defines the source file identifier packet that is presented as an<br />
argument to most PCFP functions. Include this procedure in any program that calls a<br />
PCFP function that requires a source file identifier parameter.<br />
7830 9796–013 13–1
Using PCFP with FORTRAN<br />
• FP$DFILE$ID<br />
This procedure defines the destination file identifier packet that is presented as an<br />
argument to those PCFP functions requiring both source and destination file<br />
identifier parameters. The destination file identifier packet has the same structure as<br />
the source file identifier packet; however, a different prefix is used to define the item<br />
names in this packet. Include this procedure in any program that calls a PCFP<br />
function that requires a destination file identifier parameter.<br />
• FP$GENERIC<br />
This procedure contains an illustration of the generic part of the function packet<br />
along with the prose describing the items within this portion of the function packet.<br />
This procedure contains documentation only and does not need to be included in any<br />
FORTRAN program with calls to PCFP.<br />
• FP$RTN$INFO<br />
This procedure contains an illustration of the return information portion of the<br />
function packet along with the prose describing the items within this portion of the<br />
function packet. This procedure contains documentation only and does not need to<br />
be included in any FORTRAN program with calls to PCFP.<br />
• FP$xxxxxx<br />
This generic procedure name represents the procedures that define the individual<br />
function packets. xxxxxx is between 6 and 9 characters in length and describes the<br />
function packet defined in the procedure. Each of these procedures defines all items<br />
in the following parts of the function packet:<br />
− Generic<br />
− Return information (if present)<br />
− Specific function<br />
Each of these procedures also contains<br />
− A description of the work area requirements for the function<br />
− Constants that define the minimum and maximum sizes of the work area<br />
− An illustration of the function packet<br />
− A description of each of the items within the function packet<br />
− An illustration of the form of the function call used to call the PCFP function and<br />
the arguments that must be presented on the call to the function<br />
13–2 7830 9796–013
Using PCFP with FORTRAN<br />
Your FORTRAN program must include one of these procedures for each different PCFP<br />
function that it calls.<br />
• FP$RTN$yyyy<br />
This generic procedure name represents the procedures describing the repeating<br />
information entries returned by PCFP functions. There is a procedure for each<br />
unique entry, and, in cases where both a long and a short form of the entry can be<br />
returned, a procedure exists for each case. The names of the procedures for the<br />
long and short forms of the return entries are identical, except for the last character<br />
of the name. The last character is either the letter s, which designates the short<br />
form of the entry, or the letter l, which designates the long form of the entry. Your<br />
FORTRAN program must include the appropriate procedure for each PCFP function<br />
that returns repeating information.<br />
The following procedures must be included in a FORTRAN program that calls the<br />
FP_ACQ_ELT_INFO function of PCFP.<br />
INCLUDE FP$DEFS<br />
INCLUDE FP$ERRORS<br />
INCLUDE FP$SFILE$ID<br />
INCLUDE FP$ACQELTINF<br />
INCLUDE FP$RTN$ELTL<br />
Note that the last INCLUDE statement brings in the long form of the procedure that<br />
defines the repeating information returned by this function.<br />
13.2. Naming Conventions<br />
For FORTRAN, the names of all constants, packets, and items within the packets begin<br />
with the characters FP_. If you avoid defining names beginning with these characters in<br />
your programs that call PCFP, you will have no conflicts between the names that you<br />
define and the names defined for PCFP. As with all names in FORTRAN, there is no<br />
distinction between uppercase and lowercase letters.<br />
13.2.1. Function Names<br />
The function names used in FORTRAN programs are identical to the function names<br />
given in Sections 3 – 10, except that the FORTRAN function names are all prefixed with<br />
the character sequence FP_. The FORTRAN procedures supplied with PCFP and the<br />
examples in this section follow the convention that function names appear in all<br />
uppercase letters.<br />
7830 9796–013 13–3
Using PCFP with FORTRAN<br />
13.2.2. Packet Names<br />
For FORTRAN programs, the names of all function packets, file identifier packets, and<br />
repeating return entries begin with the characters fp_. Following these characters is a 2<br />
or 3 character mnemonic that represents the type of packet being defined. An example<br />
of this is the name of the function packet for the Delete_Elt function, which is fp_de.<br />
The packet names for those repeating entry types that have both a long and a short form<br />
contain either the letter l (long entry form) or the letter s (short entry form) as their last<br />
character. For example, the names for the long and short forms of the returned file<br />
entries are fp_rfl and fp_rfs respectively. The FORTRAN procedures supplied with PCFP<br />
and the examples in this section follow the convention that packet names appear in all<br />
lowercase letters.<br />
13.2.3. Item Names Within Packets<br />
For FORTRAN programs, the names of items within the packets are prefixed with the<br />
packet name. In most cases, the remainder of the item name is the same as it appears<br />
in the section that describes and illustrates the function. (In some cases, the item name<br />
has been shortened from that described in Sections 2 – 10 to allow the total name to fit<br />
within the 31 character limit imposed on symbolic names by FORTRAN.) For example,<br />
the name for the item min_f_cycle_type found in the function packet for the<br />
ACQ_FILE_LIST function, fp_afl , is fp_afl_min_f_cycle_type. The FORTRAN procedures<br />
supplied with PCFP and the examples in this section follow the convention that item<br />
names appear in all lowercase letters.<br />
13.2.4. Names of Constants<br />
The names of all PCFP constants are defined in either the procedure FP$DEFS or the<br />
procedure FP$ERRORS. All constant names begin with the characters fp_. Following<br />
this character sequence is a sequence of characters that define the class of the<br />
constant. This sequence, in turn, is followed by the symbolic name that is found in the<br />
description for value-list type of items. For example, in the procedure that defines the<br />
function packet for the ACQ_OM_EP_INFO function, FP$ACQOMEP, the description for<br />
TEXT_TYPE states that the item is an integer value-list that can take on the values<br />
NO_CONSTRAINT, ASCII, and KANJI. These names are generic names common to all<br />
of the programming languages. LIST 7 in the procedure FP$DEFS contains the<br />
FORTRAN names for these constants: fp_text_no_constraint, fp_text_ascii, and<br />
fp_text_kanji respectively. The FORTRAN procedures supplied with PCFP and the<br />
examples in this section follow the convention that constant names appear in all<br />
lowercase letters.<br />
13.3. Form of Packet Definitions<br />
All function packets and the file identifier packets are defined as one-dimension integer<br />
type arrays. The length of these arrays is simply the length in words of the packet being<br />
defined. Repeating return entries are defined as two-dimension integer arrays:<br />
• The length of the first dimension is the length in words of the entry.<br />
• The length of the second dimension is the expected number of returned entries.<br />
13–4 7830 9796–013
Using PCFP with FORTRAN<br />
Both subscripts in the array definition for a repeating return entry are constants with<br />
names identical to the array name, except for the first character that follows fp_. For<br />
example:<br />
fp_rfl<br />
is the name of the long form of the returned file info entry.<br />
fp_lfl<br />
is the word length of this entry.<br />
fp_nfl<br />
is the expected number of these entries to be returned.<br />
The first subscript in the array definition for a repeating return entry is declared and<br />
assigned a value within the procedure containing the array definition. Prior to the<br />
INCLUDE statement containing the array definition, your program must define a constant<br />
representing the second subscript in the array definition. This constant defines the<br />
maximum number of entries you expect PCFP to return.<br />
A set of character arrays defined in the FORTRAN procedures permit character items to<br />
be defined within the packets and return entries. A character array, made equivalent<br />
(EQUIVALENCE) to the integer array, exists for each integer array that defines a function<br />
packet, file identifier packet, or repeating entry. For example:<br />
INTEGER fp_chs (17)<br />
is the integer array definition for the CHG_FILE_SEC function packet.<br />
CHARACTER*68 fp_chs_chr<br />
is the matching character array for the packet.<br />
EQUIVALENCE (fp_chs, fp_chs_chr)<br />
is the EQUIVALENCE of the two packets.<br />
Items of only two data types are defined within the PCFP structures. They are character<br />
type and integer type. The integer items are positioned within the integer arrays by<br />
means of the BITS function. The character items are positioned within the character<br />
arrays by means of the SUBSTR function.<br />
7830 9796–013 13–5
Using PCFP with FORTRAN<br />
13.4. Operating Rules and Coding Sequences<br />
This subsection describes the specific rules and coding sequence that you must use in<br />
FORTRAN programs that call PCFP.<br />
13.4.1. Specifying Items Within Packets<br />
All items within the packets are defined as statement functions and your program must<br />
refer to them as such. Use no argument when you reference those statement functions<br />
that define items within a single dimension array. For example, the following statement<br />
function reference refers to the project-id item in the CHG_FILE function packet:<br />
fp_chf_project_id()<br />
You must use one argument (that is, the entry number) when referencing any item<br />
within a repeating return entry. For example, the following statement function reference<br />
refers to the element subtype name in the ith element name entry returned by the<br />
ACQ_ELT_INFO function:<br />
fp_rll_elt_s_typ_name(i)<br />
13.4.2. Handling Repeating Return Information<br />
In setting up a call to a PCFP function that returns repeating entries, your program must<br />
declare the symbolic name of an integer constant that defines the maximum number of<br />
entries that you expect the function to return. This item is the second subscript in the<br />
statement that defines the array of return entries. For example, assume that your<br />
program calls the PCFP function ACQ_ELT_INFO. Prior to calling this function, your<br />
program must include the procedure that defines the returned element information<br />
entries. Thus, your program must contain the statement:<br />
INCLUDE FP$RTN$ELTL<br />
Note that this procedure defines the long form of the entry to be returned. This<br />
procedure contains the following array statement:<br />
INTEGER fp_rll(fp_lll,fp_nll)<br />
where the first subscript is the name of the constant that defines the length of each<br />
return entry and the second subscript is the name of the constant that defines the<br />
number of expected return entries. Your program must define the constant representing<br />
the second subscript prior to its inclusion of this procedure. Assume that you expect a<br />
maximum of 300 return element information entries. The sequence in your program to<br />
accomplish this appears as follows:<br />
INTEGER fp_nll<br />
PARAMETER ( fp_nll = 300)<br />
INCLUDE FP$RTN$ELTL<br />
Your program must also assign the return area size to the item fp_xx_rtn_area_size in the<br />
function packet, where xx represents the function mnemonic. Using the above example,<br />
13–6 7830 9796–013
Using PCFP with FORTRAN<br />
set the rtn_area_size as follows before calling the function to acquire element<br />
information:<br />
fp_ae_rtn_area_size() = fp_lll*fp_nll<br />
Finally, your program must indicate in the function packet the form of the return entries<br />
your program requires: short or long. When your program initializes the function packet,<br />
info_detail is set to its default value of short. To obtain the long form, as required by the<br />
example in this section, set info_detail to long with the following statement:<br />
fp_ae_info_detail() = fp_detail_long<br />
It is important that you make the form of the included return entries, the size of the<br />
return entry array, rtn_area_size, and info_detail compatible. If they are not compatible,<br />
either PCFP might attempt to return data into unassigned storage, or your program might<br />
not correctly interpret the data PCFP does return.<br />
If you do not want a function to return any data in the return area, define the item<br />
representing the second subscript in the array with a value of 0, and leave the item<br />
fp_xx_rtn_area_size at its initialized value of 0.<br />
13.4.3. Specifying Work Area<br />
The current release of PCFP allocates the work area internally. It is not specified in the<br />
calls to PCFP. Although PCFP allocates its work area, the calling program must still<br />
specify its size and set this value in the function packet. To assist the programmer in<br />
specifying the work area size, each procedure that defines a PCFP function packet also<br />
contains a description of the work area requirements for the function along with<br />
INTEGER and PARAMETER statements defining the maximum and minimum values for<br />
this item.<br />
13.4.4. Initializing Input Parameters<br />
Your program must initialize all input packets by filling them with zeros before calling<br />
PCFP. A suggested method of doing this is to set the entire array that represents the<br />
function or file identifier packet to 0. Thus, your program might use the following<br />
statements to zero-fill all of the input packets before calling PCFP function<br />
COPY_RAF_RAF:<br />
fp_crr = 0<br />
fp_fd = 0<br />
fp_fs = 0<br />
7830 9796–013 13–7
Using PCFP with FORTRAN<br />
13.4.5. Handling Date-Time Items<br />
Each date time item in both the input and returned parameters is two words in length<br />
and contains 1 half-word and 2 quarter-word date subitems and one 1-word time<br />
subitem. All of these subitems are declared as integers. A character overlay of the<br />
entire date-time item is also defined. This overlay allows you to perform quick<br />
comparisons on the complete date-time items. The following program part illustrates<br />
this capability. Prior to executing this part, the program called the function<br />
ACQ_ELT_INFO to return the long form of all the elements in a program file. The<br />
purpose of this program part, which is in a DO loop that looks at every returned entry, is<br />
to get the name, version, and sequence number of the most recently created element in<br />
the program file and save this information for a later display. This program part is<br />
illustrated as follows:<br />
IF (fp_rll_create_dateteim(I) .GT. last_create_datetime()) THEN<br />
last_create_datetime() = fp_rll_create_datetime(I)<br />
last_elt_name() = fp_rll_elt_name(I)<br />
last_elt_version() = fp_rll_elt_version(I)<br />
last_seq_num() = fp_rll_seq_num(I)<br />
END IF<br />
13.4.6. Calling PCFP<br />
All PCFP functions are true functions in that they return a value. This returned value is<br />
the ELMS error code generated by the function. Your program must declare the item<br />
that is assigned the returned value as type integer. This error code is also returned as an<br />
item in the function packet. The form of each function call and the number, type, and<br />
sequence of the arguments submitted on the call is illustrated at the very beginning of<br />
the procedure that describes the function packet for the function. The following<br />
example illustrates a call to the COPY_ELT function:<br />
err_code = COPY_ELT ( fp_ce, fp_fs, fp_fd, fp_rll )<br />
Note that your program must declare err_code as a type integer. Your program must<br />
specify the following four arguments on this function call:<br />
• The function packet (fp_ce)<br />
• The source file identifier packet (fp_fs)<br />
• The destination file identifier packet (fp_fd)<br />
• A return area into which PCFP returns the long form of element information (fp_rll)<br />
The COPY_SAF_SAF and COPY_RAF_SAF functions contain a zero as one of the<br />
arguments in the list. The zero is simply a placeholder for an argument that drives a<br />
feature not yet implemented. The zero must be coded in the argument list in order to<br />
maintain the proper argument order. The call to these two PCFP functions is illustrated<br />
below:<br />
err_code = COPY_RAF_SAF ( fp_crs, fp_fs, fp_fd, 0, fp_rsi)<br />
err_code = COPY_SAF_SAF ( fp_css, fp_fs, fp_fd, 0, fp_rsi, fp_rd1)<br />
13–8 7830 9796–013
13.4.7. Handling Error Conditions<br />
Using PCFP with FORTRAN<br />
Your program can determine if any warning or error occurred by examining the item<br />
error_class in the function packet. If a warning or error was returned by the function, the<br />
items error_file, sub_error_code, error_code, and aux_error_code provide further<br />
information that you can use to handle the problem. Your program can handle errors and<br />
warnings in the following ways:<br />
• Your program can print the error_msg_num portion of the error code. The number<br />
printed in this fashion corresponds to the message numbers listed in Appendix A.<br />
• Your program can check for specific error code values defined in procedure<br />
FP$ERRORS. This is necessary if your program must take special action for certain<br />
error conditions. Use the entire error code value to make the comparison.<br />
13.5. Compiling and Linking Programs That Use<br />
PCFP<br />
Compile a FORTRAN program that calls PCFP exactly as you compile any other<br />
FORTRAN program. No special statements or options are required. As stated earlier,<br />
include procedures for PCFP are contained in file SYS$LIB$*PROC$, and are found<br />
automatically by the compiler.<br />
All linking required for a FORTRAN program to call PCFP is handled transparently by the<br />
Linking System. This is true whether you use dynamic linking or static linking in your<br />
program. The file that contains PCFP executable code is in the default link search chain,<br />
so that the Linking System can always resolve references from your program to PCFP<br />
without any special statements or options.<br />
13.6. <strong>Programming</strong> Examples<br />
This subsection contains examples of three FORTRAN programs, each calling a different<br />
PCFP function. These examples correspond to those in 1.3. In the following examples,<br />
all FORTRAN commands, operators, and data specifications follow the normal FORTRAN<br />
convention of being specified in all uppercase characters. All other entities must follow<br />
the capitalization conventions specified in 13.2.<br />
7830 9796–013 13–9
Using PCFP with FORTRAN<br />
13.6.1. Calling PCFP to Delete a File<br />
This example shows a small FORTRAN program that calls the FP_DELETE_FILE function<br />
to delete the file A*B.<br />
PROGRAM EXAMPLE1<br />
*<br />
* Declare a variable to receive the value from the call to DELETE_FILE<br />
*<br />
INTEGER err_code<br />
*<br />
* INCLUDE all declarations needed to setup and call the DELETE_FILE<br />
* function<br />
*<br />
INCLUDE FP$DEFS<br />
INCLUDE FP$ERRORS<br />
INCLUDE FP$FILE$ID , LIST<br />
INCLUDE FP$DELFIL , LIST<br />
*<br />
* Zero fill the file identifier packet and insert the file name A*B into<br />
* the packet.<br />
*<br />
fp_fs = 0<br />
fp_fs_interface_level() = fp_interface_level_1<br />
fp_fs_qualifier() = 'A'<br />
fp_fs_filename() = 'B'<br />
*<br />
* Zero-fill the function packet and set parameters into the packet.<br />
* Note that we are specifying the maximum size for the work area.<br />
*<br />
fp_df = 0<br />
fp_df_interface_level() = fp_interface_level_1<br />
fp_df_work_area_size() = fp_max_work_area_delete_file<br />
*<br />
* Call DELETE_FILE function with function packet and file identifier packet<br />
*<br />
err_code = FP_DELETE_FILE (fp_df, fp_fs)<br />
*<br />
* Print any errors that were encountered during the delete operation<br />
*<br />
IF (fp_df_error_class() .NE. fp_error_class_none) THEN<br />
100 FORMAT (1X, A35, I6)<br />
PRINT 100, 'File Was Not Deleted - Error Code:',<br />
* fp_df_error_msg_num()<br />
END IF<br />
STOP<br />
END<br />
13–10 7830 9796–013
13.6.2. Calling PCFP to Copy a File<br />
Using PCFP with FORTRAN<br />
This example shows a FORTRAN program that calls the function FP_COPY_RAF_RAF to<br />
copy the mass storage file A*B(2) to another mass storage file with the internal name<br />
FILE2.<br />
PROGRAM EXAMPLE2<br />
*<br />
* Declare a variable to receive the value from the call to COPY_RAF_RAF<br />
*<br />
INTEGER err_code<br />
*<br />
* INCLUDE all declarations needed for COPY_RAF_RAF setup and call<br />
*<br />
INCLUDE FP$DEFS<br />
INCLUDE FP$ERRORS<br />
INCLUDE FP$DFILE$ID , LIST<br />
INCLUDE FP$SFILE$ID , LIST<br />
INCLUDE FP$CPYRAFRAF , LIST<br />
*<br />
* Zero fill the source file identifier packet and set file name in packet.<br />
*<br />
fp_fs = 0<br />
fp_fs_interface_level() = fp_interface_level_1<br />
fp_fs_qualifier() = 'A'<br />
fp_fs_filename() = 'B'<br />
fp_fs_f_cycle() = 2<br />
fp_fs_f_cycle_type() = fp_cycle_abs<br />
*<br />
* Zero fill the destination file identifier packet and set file name in<br />
* packet.<br />
*<br />
fp_fd = 0<br />
fp_fd_interface_level() = fp_interface_level_1<br />
fp_fd_filename() = 'FILE2'<br />
*<br />
* Zero fill the function packet and set parameters into packet.<br />
* Note that we are specifying the maximum size for the work area.<br />
*<br />
fp_crr = 0<br />
fp_crr_interface_level() = fp_interface_level_1<br />
fp_crr_work_area_size() = fp_max_work_area_copy_raf_raf<br />
fp_crr_storage_to_release() = fp_release_none<br />
*<br />
* Call COPY_RAF_RAF function with function packet and 2 file identifier<br />
* packets<br />
*<br />
err_code = FP_COPY_RAF_RAF (fp_crr, fp_fs, fp_fd)<br />
*<br />
7830 9796–013 13–11
Using PCFP with FORTRAN<br />
* If an error occurred, print prefix and the error code. Otherwise<br />
* print 'Successful Copy' along with the number of tracks that<br />
* were copied.<br />
*<br />
IF (fp_crr_error_class() .NE. fp_error_class_none) THEN<br />
100 FORMAT (1X, A34, I6)<br />
PRINT 100, 'File Was Not Copied - Error_Code: ',<br />
* fp_crr_error_msg_num()<br />
ELSE<br />
101 FORMAT (1X, A33, I8)<br />
PRINT 101, 'Successful Copy - Tracks Copied:',<br />
* fp_crr_amount_copied()/1792<br />
END IF<br />
STOP<br />
END<br />
13.6.3. Calling PCFP to Acquire Element Information from a<br />
Program File<br />
This example shows a FORTRAN program that calls the FP_ACQ_ELT_INFO function to<br />
acquire all information about the symbolic elements in program file A*B. Upon return<br />
from the function, and upon successful completion of the operation, the program prints<br />
out the number of elements that were selected and the name, version, element<br />
subtype, and sequence number of all the selected elements. If any error is returned by<br />
the PCFP function, this program prints a message with the error code.<br />
PROGRAM EXAMPLE3<br />
*<br />
* Declare a variable to receive the value from the call to ACQ_ELT_INFO<br />
*<br />
INTEGER err_code<br />
*<br />
* The parameter constant fp_nll denotes the expected number of<br />
* elements that will be selected.<br />
*<br />
INTEGER fp_nll<br />
PARAMETER ( fp_nll = 100 )<br />
*<br />
* INCLUDE all declarations needed for ACQ_ELT_INFO setup and call<br />
*<br />
INCLUDE FP$DEFS<br />
INCLUDE FP$ERRORS<br />
INCLUDE FP$SFILE$ID<br />
INCLUDE FP$ACQELTINF , LIST<br />
INCLUDE FP$RTN$ELTL , LIST<br />
*<br />
* Zero fill the source file identifier packet and set file name<br />
* in packet<br />
13–12 7830 9796–013
Using PCFP with FORTRAN<br />
*<br />
fp_fs = 0<br />
fp_fs_interface_level() = fp_interface_level_1<br />
fp_fs_qualifier() = 'A'<br />
fp_fs_filename() = 'B'<br />
*<br />
* Zero fill the function packet and set parameters into packet. Note<br />
* that we are specifying the maximum size for the work area, and<br />
* that we want to look at just the symbolic elements. Note also<br />
* we are specifying the long form of info_detail and that the size<br />
* of the return area must match the 100 (fp_nll) long entries that<br />
* we are expecting.<br />
*<br />
fp_ae = 0<br />
fp_ae_interface_level() = fp_interface_level_1<br />
fp_ae_work_area_size() = fp_max_work_area_acq_elt_info<br />
fp_ae_sym_type() = .TRUE.<br />
fp_ae_info_detail() = fp_detail_long<br />
*<br />
* Set return area size as the product of the length of the return entry<br />
* (fp_lll) and the number of expected return entries (fp_nll).<br />
*<br />
fp_ae_rtn_area_size() = fp_lll*fp_nll<br />
*<br />
* Call ACQ_ELT_INFO function with three parameters<br />
*<br />
err_code = FP_ACQ_ELT_INFO (fp_ae, fp_fs, fp_rll)<br />
IF (fp_ae_error_class() .NE. fp_error_class_none) THEN<br />
*<br />
* Print header and any error code when error_class NE none<br />
*<br />
100 FORMAT (1X, A42, I6)<br />
PRINT 100, 'ACQ_ELT_INFO Not Successful - Error Code:',<br />
* fp_ae_error_msg_num()<br />
ELSE<br />
*<br />
* Print header and the number of selected elements<br />
*<br />
102 FORMAT (1X, A29, I9)<br />
PRINT 102, 'Number of Elements S selected:', fp_ae_num_selected()<br />
*<br />
* Define line format for element information to be displayed and<br />
* then display information for each element in the file.<br />
*<br />
104 FORMAT (1X, A26, A5, I9)<br />
DO 105 I = 1, fp_ae_num_rtn_entries()<br />
105 PRINT 104, fp_rll_elt_name(I) // '/' // fp_rll_elt_version(I),<br />
* fp_rll_elt_s_typ_name(I), fp_rll_seq_num(I)<br />
END IF<br />
7830 9796–013 13–13
Using PCFP with FORTRAN<br />
STOP<br />
END<br />
13–14 7830 9796–013
Appendix A<br />
Error Messages<br />
Each PCFP error code has an explanatory message and a symbolic name associated with<br />
it. The explanatory message exists in the ELMS database and is displayed either in a<br />
print file or on the screen by ELMS when the calling program presents the associated<br />
error code to ELMS.<br />
In this appendix, each PCFP explanatory message is presented in numerical order<br />
according to the decimal value associated with the message. When displayed by ELMS,<br />
the decimal value is preceded by the PCFP component-id PRA. Inserts in a message<br />
represent variable information that is supplied by the program calling ELMS. The inserts<br />
are shown in italic. For all error codes returned in the function packet, the calling<br />
program must supply Aux_Error_Code as the first numeric insert and Error_File as the<br />
second numeric insert. For those warnings returned in Result_Indicator of the element<br />
return information (see 7.1.5 and 8.1.4), the calling program must supply the element<br />
name as the first string insert, and the element version as the second string insert.<br />
Refer to the ELMS <strong>Programming</strong> <strong>Reference</strong> <strong>Manual</strong> for details on supplying message<br />
inserts to ELMS.<br />
A Sub_Error_Code of nonzero indicates that a PCFP function called another PCFP<br />
function as part of its processing, and the called function (subfunction) encountered an<br />
error. In this case, Error_Code describes the PCFP function and the subfunction it was<br />
calling, and Sub_Error_Code and Aux_Error_Code describe the error that was<br />
encountered by the subfunction. Because two messages are available, special error<br />
message handling is required to process both error messages. The following two<br />
methods can be used to process the error messages:<br />
• Call ELMS to display the Error_Code in the normal manner. When the call is<br />
complete, concatenate the severity and component identifier from Error_Code (18<br />
bits) with the message number from Sub_Error_Code (18 bits) to create an ELMS<br />
condition identifier. Call ELMS a second time to display the subfunction error<br />
message.<br />
• Supply the value Sub_Error_Code as the third numeric insert and request an ELMS<br />
explanation level of 2. ELMS displays the message for Error_Code followed by a<br />
display of the decimal Sub_Error_Code, octal Aux_Error_Code, and decimal<br />
Error_File.<br />
In this appendix, all Error_Codes with which Sub_Error_Codes can be associated are<br />
specially noted.<br />
The symbolic name for the message appears after the heading Symbolic Name. These<br />
symbolic names are defined in copy/include element FP$ERRORS for each language<br />
7830 9796–013 A–1
Error Messages<br />
from which PCFP can be called. Any additional comments or explanations are supplied<br />
after the symbolic name.<br />
The error codes are grouped under the following headings:<br />
• Warnings and Informational Messages<br />
indicates that the function completed the operation with anomalies that should be<br />
noted<br />
• Errors<br />
indicates that the function did not complete the operation and that you need to<br />
check the program<br />
Some error messages indicate a PCFP internal error. If you receive an error of this kind,<br />
your system administrator should send a UCF describing the problem to <strong>Unisys</strong>. Other<br />
error messages indicate a system error. If you receive one of these errors, contact your<br />
system administrator to interpret the problem.<br />
A.1. Warnings and Informational Messages<br />
0001 The element / was copied as requested, but some or all of<br />
the procedure entries associated with this element were not inserted in the<br />
destination file because the procedure table in the destination file is completely<br />
full.<br />
Symbolic Name: fp_info_proc_toc_full<br />
0002 The element / was copied as requested, but some or all of<br />
the procedure entries associated with this element were not processed in the<br />
destination file because an error was encountered during procedure table<br />
operations.<br />
Symbolic Name: fp_info_proc_tbl_err<br />
0005 No name change was attempted. Either Chg_Qualifier and Chg_Filename are<br />
both FALSE or New_Qualifier and New_Filename specify the current name of<br />
the file.<br />
Symbolic Name: fp_info_no_name_chg<br />
0011 The tape file has been positioned at its logical end.<br />
Symbolic Name: fp_warn_at_saf_end<br />
As a result of the MOVE_SAF function just executed, the SAF has been<br />
positioned at its logical end.<br />
0013 The tape file has been positioned at the start of a volume.<br />
Symbolic Name: fp_warn_at_vol_start<br />
As a result of the MOVE_SAF function just executed, the SAF has been<br />
positioned at the start of one of its volumes. The logical file at this position<br />
might be a fragment continued from a previous volume; PCFP cannot copy<br />
such a logical file fragment.<br />
A–2 7830 9796–013
Error Messages<br />
0021 The performance advantage of buffered-write mode BUFTAP is negated<br />
because Omit_Log_End_Mark is FALSE.<br />
Symbolic Name: fp_warn_buftap_negated<br />
For unlabeled destination tapes when Omit_Log_End_Mark is FALSE, the<br />
COPY_RAF_SAF and COPY_SAF_SAF functions write two tape marks (WEF$)<br />
and move backward between them (MB$). This backward tape movement<br />
causes the tape subsystem to synchronize the tape (write the data from the<br />
tape unit buffer to the physical tape). This negates the performance<br />
advantages of BUFTAP, which requires constant forward tape motion and no<br />
implicit or explicit tape synchronization requests.<br />
0051 The file to be deleted was assigned by one or more other runs. The file has<br />
been marked for deletion, but the actual deletion is delayed until all other runs<br />
have freed the file.<br />
Symbolic Name: fp_warn_delete_delayed<br />
0052 The file to be changed is assigned by your run and/or by another run. The<br />
changes you requested to the read-only and write-only indicators for the file<br />
have been made, but will not take effect until all runs have freed the file.<br />
Symbolic Name: fp_warn_chg_delayed<br />
The Exec delays changing the read-only and write-only indicators for a file until<br />
no runs have the file assigned. This includes the run that requested the change<br />
to these indicators. Any other changes requested for the file have been made<br />
and take effect immediately.<br />
0053 PCFP could not complete the requested privacy change for files<br />
of the F-cycle set because the files were in a ‘to be cataloged’ state for another<br />
run.<br />
Symbolic Name: fp_warn_chg_incomplete<br />
For CHG_FILE_KEYS this warning is returned when changing the keys for a<br />
removable pack F-cycle set. For CHG_FILE_SEC this warning is returned when<br />
changing the MFD Main Item privacy bit for an F-cycle set and when changing<br />
the clearance level, file owner user-id or ACR for a removable pack F-cycle set.<br />
To perform these changes PCFP must assign each file in the F-cycle set. The<br />
is the number of members of the F-cycle set that are currently<br />
“to be cataloged” by a different run and cannot be assigned and changed. Note<br />
that PCFP does not attempt to assign and change F-cycle members that are<br />
marked as “to be deleted.”<br />
To assure that all files in the F-cycle set have the same values, the PCFP<br />
function should be repeated after the “to be cataloged” F-cycle members are<br />
freed by the other run. Setting the WAIT_ON_FACILITIES item in the generic<br />
part of the function packet to TRUE assures that all F-cycle members have<br />
been freed before proceeding.<br />
0054 Name change completed for cataloged tape file. If this is a labeled tape file that<br />
was previously written without the F file assignment option, the tape cannot be<br />
read when assigned with the new file name.<br />
Symbolic Name: fp_warn_tape_may_be_unreadable<br />
7830 9796–013 A–3
Error Messages<br />
0071 The element / was not copied because the destination file<br />
contains an element with the same name, version, and type.<br />
Symbolic Name: fp_warn_elt_conflict<br />
0072 The element / was not copied because the destination file<br />
contains an element with the same name, version, and type, and a date and<br />
time of creation which is more recent.<br />
Symbolic Name: fp_warn_elt_not_newer<br />
0073 The symbolic element / was not copied because the<br />
specific cycle specified does not exist.<br />
Symbolic Name: fp_warn_nonexistent_sym_cycle<br />
0076 The element / could not be copied or changed because the<br />
new name generated for the element contains an embedded space.<br />
Symbolic Name: fp_warn_bad_elt_name<br />
0077 The element / could not be copied or changed because the<br />
new version generated for the element contains an embedded space.<br />
Symbolic Name: fp_warn_bad_elt_version<br />
0078 The omnibus element / could not be changed because the<br />
new subtype is not legal for an omnibus element.<br />
Symbolic Name: fp_warn_bad_subtype<br />
Omnibus subtypes must be between 0 and 63.<br />
0080 The element / could not be undeleted because the relative<br />
sequence number specified in Seq_Num does not exist.<br />
Symbolic Name: fp_warn_elt_rel_seq_num_err<br />
The returned element entry that contains this error code is the member of the<br />
element/version/type set that has the lowest sequence number.<br />
0081 The element / is already undeleted.<br />
Symbolic Name: fp_warn_elt_undeleted<br />
0082 The element / could not be undeleted because another<br />
member of the element/version/type set is undeleted and Allow_Deletion does<br />
not allow its deletion.<br />
Symbolic Name: fp_warn_elt_delete_not_allowed<br />
A.2. Errors<br />
Errors are grouped into the following categories:<br />
• Calling program errors<br />
A–4 7830 9796–013
• Execution I/O errors<br />
• Execution errors other than I/O errors—all file types<br />
• Execution errors other than I/O errors—sequential-access files<br />
• Execution errors other than I/O errors—random-access files<br />
• Execution errors other than I/O errors—program files<br />
• Errors associated with assigning and freeing files<br />
• Errors associated with the PACK_PF function<br />
A.2.1. Calling Program Errors<br />
Error Messages<br />
1002 Calling Program Error: The value specified for Qualifier in the file identifier with<br />
index is not legal. For the Acq_File_List function, this error<br />
indicates that the Qualifier specified in the function packet is not legal. For the<br />
Chg_File_Name function, if index is 0 this error indicates that the New_Qualifier<br />
specified in the function packet is not legal.<br />
Symbolic Name: fp_err_bad_qualifier<br />
The qualifier must be 1 to 12 characters in length, left justified, space filled or<br />
null terminated. It must be composed from the characters A – Z, 0 – 9, $, -. A<br />
value of all spaces or all nulls is also legal. For the Acq_File_List function, the<br />
qualifier can also contain the wild-card characters (? and *).<br />
1003 Calling Program Error: The value specified for Filename in the file identifier with<br />
index is not legal. For the Acq_File_List function, this error<br />
indicates that the Filename specified in the function packet is not legal. For the<br />
Chg_File_Name function, if index is 0, this error indicates that the New_Filename<br />
specified in the function packet is not legal.<br />
Symbolic Name: fp_err_bad_filename<br />
The file name must be 1 to 12 characters in length, left justified, space filled or<br />
null terminated. It must be composed from the characters A – Z, 0 – 9, $, -. A<br />
value of all spaces or all nulls is not legal. For the Acq_File_List function, the file<br />
name can also contain the wild-card characters (? and *). Also, in this context, a<br />
null value is legal.<br />
7830 9796–013 A–5
Error Messages<br />
1005 Calling Program Error: The value specified for Directory_Id in the file identifier<br />
with index is not legal. For the Acq_File_List function, this error<br />
indicates that the Directory_Id specified in the function packet is not legal.<br />
Symbolic Name: fp_err_bad_directory_id<br />
The only legal values for Directory_Id are null, STD, and SHARED. A value of all<br />
spaces is also allowed in the file identifier only. The value SHARED is allowed<br />
only if Multi-Host File Sharing (MHFS) is configured on the system.<br />
1006 Calling Program Error: The value specified for F_Cycle_Type in the file identifier<br />
with index is not legal. For the Acq_File_List function, this error<br />
indicates that the value specified for F_Cycle_Type in the function packet is not<br />
legal.<br />
Symbolic Name: fp_err_bad_f_cycle_type<br />
The only legal values for F_Cycle_Type are unspecified (0), abs (1), and rel (2).<br />
1007 Calling Program Error: The value specified for F_Cycle in the file identifier with<br />
index is not legal. For the Acq_File_List function, this error<br />
indicates that the value specified for F_Cycle in the function packet is not legal.<br />
Symbolic Name: fp_err_bad_f_cycle<br />
When F_Cycle_Type = unspecified (0), F_Cycle must be zero. When<br />
F_Cycle_Type = abs (1), F_Cycle must be between 1 and 999 inclusive. When<br />
F_Cycle_Type = rel (2), F_Cycle must be between -31 and 1 inclusive.<br />
1017 Calling Program Error: A value was specified for F_Cycle in the file identifier<br />
with index . A specific F-cycle cannot be specified for the<br />
function you requested, because that function operates on all files in the Fcycle<br />
series.<br />
Symbolic Name: fp_err_unalwd_f_cycle<br />
1041 PCFP Internal Error<br />
Symbolic Name: fp_err_fct_pkt_range<br />
The function packet parameter supplied to PCFP extends outside of the<br />
address range MIN_DATA_ADDR to MAX_DATA_ADDR. Note that a few<br />
functions have a different address range, as documented in the work area<br />
descriptions in Sections 3 – 10. For compiler calling programs, this error<br />
indicates a problem with the interface routine.<br />
1042 PCFP Internal Error<br />
Symbolic Name: fp_err_file_id_range<br />
A file identifier parameter supplied to PCFP extends outside of the address<br />
range MIN_DATA_ADDR to MAX_DATA_ADDR. Note that a few functions<br />
have a different address range, as documented in the work area descriptions in<br />
Sections 3 – 10. For compiler calling programs, this error indicates a problem<br />
with the interface routine.<br />
A–6 7830 9796–013
Error Messages<br />
1043 Calling Program Error: The total size of the return area and the work area<br />
exceeds the maximum allowed.<br />
Symbolic Name: fp_err_work_area_range<br />
The work area parameter supplied to PCFP extends outside of the address<br />
range MIN_DATA_ADDR to MAX_DATA_ADDR. For compiler calling programs,<br />
this error indicates the total size of the return area and work area exceeds<br />
approximately 238,000 words. Note that a few functions have a different<br />
address range and maximum return area and work area size, as documented in<br />
the work area descriptions in Sections 3 – 10.<br />
1044 Calling Program Error: The total size of the return area and the work area<br />
exceeds the maximum allowed.<br />
Symbolic Name: fp_err_return_area_range<br />
The return area parameter supplied to PCFP extends outside of the address<br />
range MIN_DATA_ADDR to MAX_DATA_ADDR. For compiler calling programs,<br />
this error indicates the total size of the return area and work area exceeds<br />
approximately 238,000 words. Note that a few functions have a different<br />
address range and maximum return area and work area size, as documented in<br />
the work area descriptions in Sections 3 – 10.<br />
1045 PCFP Internal Error<br />
Symbolic Name: fp_err_stack_range<br />
The PLUS stack for PCFP extends outside of the address range<br />
MIN_DATA_ADDR to MAX_DATA_ADDR. Note that a few functions have a<br />
different address range, as documented in the work area descriptions in<br />
Sections 3 – 10. For compiler calling programs, this error indicates a problem<br />
with the interface routine.<br />
1046 PCFP Internal Error<br />
Symbolic Name: fp_err_stack_size<br />
The PLUS stack for PCFP is smaller than the 400 words required. For compiler<br />
calling programs, this error indicates a problem with the interface routine.<br />
1047 PCFP Internal Error<br />
Symbolic Name: fp_err_desc_area_range<br />
The descriptor return area parameter supplied to PCFP extends outside of the<br />
address range of MIN_DATA_ADDR to MAX_DATA_ADDR. For compiler<br />
calling programs, this error indicates a problem with the interface routine.<br />
7830 9796–013 A–7
Error Messages<br />
1048 PCFP Internal Error<br />
Symbolic Name: fp_err_work_space_range<br />
The PLUS work space for PCFP extends outside of the address range of<br />
MIN_DATA_ADDR to MAX_DATA_ADDR. Note that a few functions have a<br />
different address range, as documented in the work area descriptions in<br />
Sections 3 – 10. For compiler calling programs, this error indicates a problem<br />
with the interface routine.<br />
1050 Calling Program Error: An unused portion of a packet passed to PCFP contains a<br />
nonzero value.<br />
Symbolic Name: fp_err_nonzero_filler<br />
All such items must be initialized to zero by the caller.<br />
1052 Calling Program Error: The value specified for Interface_Level in the function<br />
packet or file identifier packet is illegal.<br />
Symbolic Name: fp_err_bad_interface_level<br />
The Interface_Level for file identifier packets is described in 2.3. The<br />
Interface_Level for the generic part of the function packet is described in 2.4.1.<br />
The individual function packet documentation in Sections 3 – 10 describes the<br />
most current interface level for each function that supports interface levels<br />
other than fp_interface_level_1.<br />
1053 PCFP Internal Error<br />
Symbolic Name: fp_err_no_work_area<br />
The pointer to the work area (last parameter) is null. For compiler calling<br />
programs this error indicates a problem with the interface routine.<br />
1054 Calling Program Error: The value specified for Work_Area_Size in the function<br />
packet is smaller than the minimum required by the function.<br />
Symbolic Name: fp_err_small_work_area<br />
1055 Calling Program Error: The value specified for Return_Area_Size in the function<br />
packet is > 0 but the Return Area parameter is null.<br />
Symbolic Name: fp_err_bad_return_area<br />
A–8 7830 9796–013
Error Messages<br />
1056 Calling Program Error: The value specified for Work_Area_Size in the PREP_PF<br />
function packet is smaller than the amount required for <br />
relocatable entry points.<br />
Symbolic Name: fp_err_small_prep_pf_work_area<br />
The program file has the number of relocatable entry points shown in the<br />
message and contained in the Aux_Error_Code item in the generic part of the<br />
function packet. Use this value and the formula described in 8.5.4 to calculate<br />
the required value for Work_Area_Size. Call the PREP_PF function again with<br />
this value.<br />
1062 Calling Program Error: The value specified for Return_Area_Size in the function<br />
packet is smaller than the minimum required by the function.<br />
Symbolic Name: fp_err_small_return_area<br />
1072 Calling Program Error: The value specified for Num_Dest_Files in the function<br />
packet is not legal.<br />
Symbolic Name: fp_err_bad_num_dest_files<br />
Currently, the only legal value for Num_Dest_Files is 1.<br />
1073 The file with index is not a Random-Access File, but the function<br />
requires such a file.<br />
Symbolic Name: fp_err_not_raf<br />
1074 The file with index is not a Sequential-Access File, but the<br />
function requires such a file.<br />
Symbolic Name: fp_err_not_saf<br />
1201 Calling Program Error: The value specified for Dest_Format in the function<br />
packet is not legal.<br />
Symbolic Name: fp_err_bad_format<br />
The only legal value for Dest_Format is furpur (1).<br />
1202 Calling Program Error: The value specified for On_End_Of_File or<br />
On_End_Of_Dest_File in the function packet is not legal.<br />
Symbolic Name: fp_err_bad_on_end_dest<br />
The only legal values are rtn_error (0), extend_to_blank_volume (1), and<br />
solicit_opr (1).<br />
7830 9796–013 A–9
Error Messages<br />
1203 Calling Program Error: The value specified for On_End_Of_File or<br />
On_End_of_Source_File in the function packet is not legal.<br />
Symbolic Name: fp_err_bad_on_end_source<br />
The only legal values are rtn_error (0), extend_to_blank_volume (1), and<br />
solicit_opr (1).<br />
1204 PCFP Internal Error<br />
Symbolic Name: fp_err_vol_subr_required<br />
1205 PCFP Internal Error<br />
Symbolic Name: fp_err_vol_subr_unalwd<br />
1206 PCFP Internal Error<br />
Symbolic Name: fp_err_bad_data_size<br />
1207 PCFP Internal Error<br />
Symbolic Name: fp_err_aux_info_unalwd<br />
1208 Calling Program Error: The item Synchronize can be TRUE only if<br />
Interface_Level is at least .<br />
Symbolic Name: fp_err_bad_synchronize<br />
1209 Calling Program Error: The item Write_Obsolete_Variant can be TRUE only if<br />
the size of Dest_Block_Size is 0 or 1.<br />
Symbolic Name: fp_err_obsolete_variant_unalwd<br />
The obsolete variant of the FURPUR tape format requires that each tape block<br />
contains one mass storage track.<br />
1210 Calling Program Error: The item Return_Block_Id can be TRUE only if<br />
Interface_Level is at least 2.<br />
Symbolic Name: fp_err_bad_return_block_id<br />
1211 Calling Program Error: The value specified for On_Conflict in the function packet<br />
is not legal.<br />
Symbolic Name: fp_err_bad_on_conflict<br />
The only legal values for On_Conflict are do_not_copy (0), delete_original (1),<br />
and copy_if_newer (2).<br />
1212 Calling Program Error: The value specified for Info_to_Return in the function<br />
packet is not legal.<br />
Symbolic Name: fp_err_bad_info_to_return<br />
The only legal values for Info_to_Return are none (0), error_only (1),<br />
nonerror_only (2), and all_info (3).<br />
A–10 7830 9796–013
Error Messages<br />
1213 Calling Program Error: The value specified for Info_Detail in the function packet<br />
is not legal.<br />
Symbolic Name: fp_err_bad_info_detail<br />
The only legal values for Info_Detail are short (0) and long (1). The functions<br />
Acq_File_Info and Acq_File_List also allow the value complete (2).<br />
1214 Calling Program error: The value specified for Elt_Name, New_Elt_Name or<br />
Dest_Elt_Name in the function packet is not legal.<br />
Symbolic Name: fp_err_bad_elt_name<br />
The Elt_Name, New_Elt_Name and Dest_Elt_Name must be 1 to 12 characters<br />
in length, left justified, space filled or null terminated. It must be composed<br />
from the characters A – Z, 0 – 9, $, -. A value of all nulls is legal. A value of all<br />
spaces is not legal. See the function description for the use of the wild-card<br />
characters (- and *).<br />
1215 Calling Program Error: The value specified for Elt_Version, New_Elt_Version or<br />
Dest_Elt_Version in the function packet is not legal.<br />
Symbolic Name: fp_err_bad_elt_version<br />
The Elt_Version must be 1 to 12 characters in length, left justified, space filled<br />
or null terminated. It must be composed from the characters A – Z, 0 – 9, $, -.<br />
A value of all spaces is legal. See the function description for the use of all<br />
nulls and wild-card characters (? and *).<br />
1216 Calling Program Error: The value specified for Cycle_Type in the function packet<br />
is not legal.<br />
Symbolic Name: fp_err_bad_cycle_type<br />
The only legal values for Cycle_Type are unspecified (0), abs (1), and rel (2).<br />
1217 Calling Program Error: The value specified for Cycle_Num in the function packet<br />
is not legal.<br />
Symbolic Name: fp_err_bad_cycle_num<br />
When Cycle_Type = unspecified (0), Cycle_Num must be zero. When<br />
Cycle_Type = abs (1), Cycle_Num must be between 0 and 62 inclusive. When<br />
Cycle_Type = rel (2), Cycle_Num must be between -62 and 0 inclusive.<br />
1218 Calling Program Error: The value specified for Dest_Sym_Subtype,<br />
Dest_Omn_Subtype, or New_Omn_Sym_Subtype in the function packet is not<br />
legal.<br />
Symbolic Name: fp_err_bad_subtype<br />
Symbolic subtypes must be between 0 and 66. Omnibus subtypes must be<br />
between 0 and 63. Absolute subtypes must be between 0 and 4.<br />
1219 Calling Program Error: The value specified for New_Cycle_Limit in the function<br />
packet is not legal.<br />
Symbolic Name: fp_err_bad_cycle_limit<br />
The value of the New_Cycle_Limit must be between 0 and 63 inclusive.<br />
7830 9796–013 A–11
Error Messages<br />
1221 Calling Program Error: The value specified for Storage_to_Release in the<br />
function packet is not legal.<br />
Symbolic Name: fp_err_bad_storage_to_release<br />
The legal values for Storage_to_Release are none (0), all_but_initial_reserve (1),<br />
and all_storage (2).<br />
1222 Calling Program Error: The value specified for Pack_Method in the function<br />
packet is not legal.<br />
Symbolic Name: fp_err_bad_pack_method<br />
1224 Calling Program Error: The value specified for EP_Name in the function packet<br />
is not legal.<br />
Symbolic Name: fp_err_bad_ep_name<br />
Either the EP_Name contains illegal characters, or a value other than zero was<br />
specified and the value of Text_Type was given a value other than ASCII (1).<br />
The EP_Name must be 1 to 32 characters in length, left justified, space filled or<br />
null terminated. The EP_Name may contain the wild-card characters (? and *).<br />
A value of all nulls is legal. A value of all spaces is not legal.<br />
1225 Calling Program Error: The value specified for Proc_Name in the function packet<br />
is not legal.<br />
Symbolic Name: fp_err_bad_proc_name<br />
The Proc_Name must be 1 to 30 characters in length, left justified, space filled<br />
or null terminated. The name can be longer than 12 characters only if<br />
Proc_Table is set to cobol_proc. It must be composed from the legal<br />
characters for procedure names. The Proc_Name may also contain the wildcard<br />
characters (? and *). A value of all nulls is legal. A value of all spaces is<br />
not legal.<br />
1227 Calling Program Error: The value specified for Proc_Table in the function packet<br />
is not legal.<br />
Symbolic Name: fp_err_bad_proc_table<br />
The only legal values for Proc_Table are masm_proc (2), cobol_proc (3), and<br />
ftn_pls_proc (4).<br />
1228 Calling Program Error: The value specified for Text_Type in the function packet<br />
is not legal.<br />
Symbolic Name: fp_err_bad_text_type<br />
The only legal values for Text_Type are no_constraint (0), ASCII (1) and Kanji (3).<br />
A–12 7830 9796–013
Error Messages<br />
1229 Calling Program Error: The value specified for SCS_Conformance in the function<br />
packet is not legal.<br />
Symbolic Name: fp_err_bad_scs_conformance<br />
The only legal values for SCS_Conformance are no_constraint (0), none (1),<br />
loose (16), and strict (17).<br />
1231 Calling Program Error: The value specified for Char_Type in the function packet<br />
is not legal.<br />
Symbolic Name: fp_err_bad_char_type<br />
The only legal values for Char_Type are both (0), ASCII (1), and Fieldata (2).<br />
1232 Calling Program Error: The value specified for Deletion in the function packet is<br />
not legal.<br />
Symbolic Name: fp_err_bad_deletion<br />
The only legal values for Deletion are undeleted (0), deleted (1), and both (2).<br />
1233 Calling Program Error: The value specified for Min_Date_Time in the function<br />
packet exceeds the corresponding value for Max_Date_Time.<br />
Symbolic Name: fp_err_bad_date_time<br />
For the function Acq_File_List, this error can refer to the values for<br />
Create_Date_Time or Ref_Date_Time or Backup_Date_Time.<br />
1234 Calling Program Error: The value specified for Min_Seq_Num in the function<br />
packet exceeds the value for Max_Seq_Num.<br />
Symbolic Name: fp_err_bad_seq_num<br />
1235 Calling Program Error: The value specified for Min_Size in the function packet<br />
exceeds the value for Max_Size.<br />
Symbolic Name: fp_err_bad_seq_num<br />
1241 Calling Program Error: The value specified for EP_Type in the function packet is<br />
not legal.<br />
Symbolic Name: fp_err_bad_ep_type<br />
The legal values for EP_Type are rel_ep (1), om_ep (2), and both (3).<br />
1245 Calling Program Error: The value specified for Action in the function packet is<br />
not legal.<br />
Symbolic Name: fp_err_bad_action<br />
The legal values for Action are overcopy (0) and must_be_empty (1).<br />
7830 9796–013 A–13
Error Messages<br />
1247 Calling Program Error: The value specified for Seq_Num_Type in the function<br />
packet is not legal.<br />
Symbolic Name: fp_err_bad_seq_num_type<br />
The only legal values for Seq_Num_Type are rel (0) and abs (1).<br />
1248 Calling Program Error: The value specified for Seq_Num in the function packet<br />
is not legal.<br />
Symbolic Name: fp_err_bad_elt_seq_num<br />
When Seq_Num_Type = rel (0), Seq_Num must be between -26,145 and 0<br />
inclusive. When Seq_Num_Type = abs (1), Seq_Num must be between 1 and<br />
26,146 inclusive.<br />
1249 Calling Program Error: When Seq_Num_Type is set to abs in the function<br />
packet, Elt_Name and Elt_Version must have null values and Abs_Type,<br />
Omn_Type, Rel_Type, Sym_Type, the Omn_Sym_Subtype array and the<br />
Abs_Subtype array must all be FALSE.<br />
Symbolic Name: fp_err_elt_selection_conflict<br />
Elt_Name, Elt_Version, Abs_Type, Omn_Type, Rel_Type, Sym_Type,<br />
Omn_Sym_Subtype or Abs_Subtype can only be specified by the calling<br />
program when Seq_Num_Type is set to rel (0) and when Seq_Num contains a<br />
relative sequence number (-26,145 through 0, inclusive).<br />
1250 Calling Program Error: The value specified for Site_Info in the function packet<br />
must be zero when Select_on_Site_Info or Change_Site_Info is not set to<br />
TRUE.<br />
Symbolic Name: fp_err_bad_site_info<br />
1251 Calling Program Error: The value specified for Rollout_Prohibited in the function<br />
packet is not legal.<br />
Symbolic Name: fp_err_bad_rollout_prohibited<br />
The legal values for Rollout_Prohibited are no_chg (0), set_off (1), and set_on<br />
(2).<br />
1252 Calling Program Error: The value specified for Read_Only in the function packet<br />
is not legal.<br />
Symbolic Name: fp_err_bad_read_only<br />
The legal values for Read_Only are no_chg (0), set_off (1), and set_on (2).<br />
1253 Calling Program Error: The value specified for Write_Only in the function packet<br />
is not legal.<br />
Symbolic Name: fp_err_bad_write_only<br />
The only legal values for Write_Only are no_chg (0), set_off (1), and set_on (2).<br />
A–14 7830 9796–013
Error Messages<br />
1254 Calling Program Error: The value specified for Directory_Disable in the function<br />
packet is not legal.<br />
Symbolic Name: fp_err_bad_directory_disable<br />
The only legal values for Directory_Disable are no_chg (0), set_off (1), and<br />
set_on (2).<br />
1255 Calling Program Error: The value specified for Write_Disable in the function<br />
packet is not legal.<br />
Symbolic Name: fp_err_bad_write_disable<br />
The only legal values for Write_Disable are no_chg (0), set_off (1), and set_on<br />
(2).<br />
1256 Calling Program Error: The value specified for Backup_Disable in the function<br />
packet is not legal.<br />
Symbolic Name: fp_err_bad_backup_disable<br />
The only legal values for Backup_Disable are no_chg (0), set_off (1), and set_on<br />
(2).<br />
1257 Calling Program Error: The value specified for Cache_Disable in the function<br />
packet is not legal.<br />
Symbolic Name: fp_err_bad_cache_disable<br />
The only legal values for Cache_Disable are no_chg (0), set_off (1), and set_on<br />
(2).<br />
7830 9796–013 A–15
Error Messages<br />
1258 Calling Program Error: The value specified for Init_Program_File or<br />
Init_Dest_File in the function packet is not legal.<br />
Symbolic Name: fp_err_bad_init_prog_file<br />
The legal values for Init_Program_File or Init_Dest_File are none (0), pf (1), lpf<br />
(2), standard_lepf (3), and large_lepf (4). For the COPY_ELT function<br />
Init_Dest_File also has the legal value source_file_type (5).<br />
1261 Calling Program Error: The value specified for Project_Id or Account_Id in the<br />
function packet is not legal.<br />
Symbolic Name: fp_err_bad_project_account_id<br />
The Project_Id or Account_Id must be 1 to 12 characters in length, left justified,<br />
space filled or null terminated. The Project_Id must be composed from the<br />
characters A – Z, 0 – 9, hyphen ( - ), and the dollar sign ($). The Account_Id<br />
must be composed from the characters A – Z, 0 – 9, hyphen ( - ), and the period<br />
( . ). A value of null is legal. A value of all spaces is not legal. For the<br />
Acq_File_List function, the Project_Id or Account_Id may also contain the<br />
wild-card characters (? and *).<br />
1265 Calling Program Error: The value specified for Max_F_Cycles in the function<br />
packet is not legal.<br />
Symbolic Name: fp_err_bad_max_f_cycles<br />
The value for Max_F_Cycles must be between 0 and 32.<br />
1271 Calling Program Error: The value specified for Privacy in the function packet is<br />
not legal.<br />
Symbolic Name: fp_err_bad_privacy<br />
The only legal values for Privacy are no_chg (0), private (1), semiprivate (2), and<br />
public (3).<br />
1272 Calling Program Error: The value specified for New_Read_Key or for<br />
New_Write_Key in the function packet is not legal.<br />
Symbolic Name: fp_err_bad_new_key<br />
The values for New_Read_Key and New_Write_Key must be 0 to 6 characters<br />
in length, left justified, and either space filled or null terminated. They can be<br />
composed of any character except the following: the comma ( , ), the slash ( / ),<br />
the semi-colon ( ; ), and the period ( . ). A value of all nulls is legal and indicates<br />
the key is not to be changed. A value of all spaces is legal and indicates the<br />
key is to be removed.<br />
A–16 7830 9796–013
Error Messages<br />
1275 Calling Program Error: The value specified for ACR_Name in the function packet<br />
is not legal.<br />
Symbolic Name: fp_err_bad_acr_name<br />
The value for ACR_Name must be 1 to 6 characters in length, left justified, and<br />
either space filled or null terminated. It must be the name of an existing ACR<br />
composed from the characters A – Z, 0 – 9. The ACR must be owned by the<br />
user-id of the run calling PCFP. A value of null is not legal if Privacy is set to<br />
semiprivate. A value of null is required if Privacy is set to any value except<br />
semiprivate.<br />
1276 Calling Program Error: The value specified for File_Owner_User_Id in the<br />
function packet is not legal.<br />
Symbolic Name: fp_err_bad_file_owner_user_id<br />
If Chg_File_Owner_User_Id is FALSE, File_Owner_User_Id cannot be specified.<br />
The values for File_Owner_User_Id must be 0 to 6 characters in length, left<br />
justified, and either space filled or null terminated. They must be composed<br />
from the characters A – Z, 0 – 9. A value of all nulls is legal and will cause the<br />
file to be unowned if Chg_File_Owner_User_Id is set to TRUE. This item must<br />
be all nulls unless Chg_File_Owner_User_Id is set to TRUE.<br />
1277 Calling Program Error: The value specified for Clearance_Level in the function<br />
packet is not legal.<br />
Symbolic Name: fp_err_bad_clearance_level<br />
If Chg_Clearance_Level is FALSE, Clearance_Level cannot be specified. The<br />
legal values for Clearance_Level are between 0 and 62 inclusive.<br />
1281 Calling Program Error: The value specified for Search_Set in the function packet<br />
is not legal.<br />
Symbolic Name: fp_err_bad_search_set<br />
The only legal values for Search_Set are asgd_to_run (1), known_to_run (2) and<br />
catalog_directory (3).<br />
1282 Calling Program Error: The value specified for Lifetime in the function packet is<br />
not legal.<br />
Symbolic Name: fp_err_bad_lifetime<br />
The only legal values for Lifetime are no_constraint (0), cataloged (1) and<br />
temporary (2).<br />
1283 Calling Program Error: When both a Min_F_Cycle_Type and a<br />
Max_F_Cycle_Type are specified, either both must be abs (1) or both must be<br />
rel (2).<br />
Symbolic Name: fp_err_incompat_f_cycle_types<br />
7830 9796–013 A–17
Error Messages<br />
1284 Calling Program Error: The value specified for Equip_Type in the function packet<br />
is not legal.<br />
Symbolic Name: fp_err_bad_equip_type<br />
The legal values for Equip_Type are none (0), mass_storage (1), tape (2), and<br />
miscellaneous (3).<br />
1285 Calling Program Error: A selection attribute was specified that is not in the set<br />
of attributes requested.<br />
Symbolic Name: fp_err_bad_qualification<br />
For the Acq_File_List function, an attribute cannot be used to qualify the files<br />
selected unless the calling program has also specified that the attribute is to be<br />
included in the information to be returned by the function.<br />
1286 Calling Program Error: The values specified for Lifetime and Search-Set in the<br />
function packet are not compatible.<br />
Symbolic Name: fp_err_incompat_life_srch_set<br />
When Lifetime has a value of Temporary(2), Search_Set cannot have a value of<br />
Catalog_Directory(3) since temporary files are never represented in the<br />
directory of cataloged files.<br />
1301 Calling Program Error: The value specified for Type_of_Move in the function<br />
packet is not legal.<br />
Symbolic Name: fp_err_bad_type_of_move<br />
The only legal values for Type_of_Move are forward (0), backward (1),<br />
to_saf_end (2) and to_saf_start (3).<br />
1302 Calling Program Error: The value specified for Move_Num in the function<br />
packet is not legal for the Type_of_Move specified.<br />
Symbolic Name: fp_err_bad_move_num<br />
Move_Num must be zero if Type_of_Move is to_saf_end or to_saf_start and<br />
not zero if Type_of_Move is backward.<br />
1303 Calling Program Error: The value specified for Current_Vol_Only in the function<br />
packet is not legal for the Type_Of_Move specified.<br />
Symbolic Name: fp_err_bad_current_vol_only<br />
Current_Vol_Only must be set to TRUE if the Type_of_Move is backward.<br />
A–18 7830 9796–013
Error Messages<br />
1304 Calling Program Error: The value specified for Position_At_End_Of_Log_File in<br />
the function packet is not legal.<br />
Symbolic Name: fp_err_bad_position_at_end<br />
Position_At_End_Of_Log_File can be set to TRUE only if Type_of_Move is set<br />
to backward.<br />
1305 Calling Program Error: The value specified for Interlock in the function packet is<br />
not legal.<br />
Symbolic Name: fp_err_bad_interlock<br />
Interlock can be set to TRUE only if Type_of_Move is set to to_saf_start.<br />
1306 Calling Program Error: The value specified for Move_At_End in the function<br />
packet is not legal.<br />
Symbolic Name: fp_err_bad_move_at_end<br />
1307 Calling Program Error: The item Type_Of_Move can have a value of<br />
To_Block_Id only if Interface_Level is at least 2.<br />
Symbolic Name: fp_err_bad_to_block_id<br />
1308 Calling Program Error: The value specified for Move_Block_Id must be zero for<br />
the Type_Of_Move specified.<br />
Symbolic Name: fp_err_nonzero_move_block_id<br />
1309 Calling Program Error: The value specified for Move_Block_Id is not a legal<br />
block-id.<br />
Symbolic Name: fp_err_illegal_move_block_id<br />
This error is most likely to occur when the special block-id value of –1 (octal<br />
value 0777777777776) or –2 (octal value 0777777777775) is incorrectly used as<br />
the Move_Block_Id value. The special block-id value of –1 is returned by PCFP<br />
functions when fast tape access is not supported for the requested tape file.<br />
The special block-id value of –2 can be returned by the COPY_SAF_RAF and<br />
MOVE_SAF functions when a labeled tape is positioned to its logical end. The<br />
error could also occur when the value stored in Move_Block_Id is not a block-id<br />
returned by a previous RBIDW$ or RBKID$ I/O function.<br />
7830 9796–013 A–19
Error Messages<br />
1401 Calling Program Error: The value specified for Exclusive_Assign in the function<br />
packet is not legal.<br />
Symbolic Name: fp_err_exclusive_required<br />
Exclusive_Assign is set to FALSE but the requested operation requires<br />
exclusive assignment of the file.<br />
1501 Calling Program Error: A subroutine for processing the descriptor on the<br />
sources tape file was specified without also specifying the item<br />
Source_Format.<br />
Symbolic Name: fp_err_src_format_req<br />
A nonzero value for the item Source_Format is always required whenever a<br />
subroutine for processing the descriptor on the source tape is specified by<br />
means of a nonzero value in the item Source_Format.<br />
1502 Calling Program Error: A virtual address contained in the Src_Desc_Subr or<br />
Dest_Desc_Subr is illegal in that the BDI portion or the Offset portion is 0.<br />
Symbolic Name: fp_err_badly_formed_va<br />
1503 Calling Program Error: The Event_Array has an Event(i) set to TRUE that is not<br />
supported for this function.<br />
Symbolic Name: fp_err_bad_event<br />
1504 Calling Program Error: Event_Array cannot be specified without also specifying<br />
Caller_Subr.<br />
Symbolic Name: fp_err_caller_subr_required<br />
1505 Calling Program Error: Neither Src_Desc_Subr nor Dest_Desc_Subr may be<br />
specified when Event_Array and Caller_Subr are specified.<br />
Symbolic Name: fp_err_desc_subr_not_allowed<br />
1506 Calling Program Error: Caller_Subr cannot be specified without also specifying<br />
at least one Event(i) as TRUE in the Event_Array.<br />
Symbolic Name: fp_err_caller_subr_not_allowed<br />
1507 Calling Program Error: The specified Caller_Subr virtual address is invalid,<br />
having either a zero BDI or a zero offset.<br />
Symbolic Name: fp_err_caller_subr_bad_va<br />
A–20 7830 9796–013
A.2.2. Execution I/O Errors<br />
Error Messages<br />
2001 Unexpected I/O status was returned by a read (R$) request to<br />
the file with index .<br />
Symbolic Name: fp_err_bad_io_r<br />
2002 Unexpected I/O status was returned by a scatter-read (SCR$)<br />
request to the file with index .<br />
Symbolic Name: fp_err_bad_io_scr<br />
2004 Unexpected I/O status was returned by a multiple-request (MR$)<br />
read (R$) request to the file with index .<br />
Symbolic Name: fp_err_bad_io_mr_r<br />
2005 Unexpected I/O status was returned by a move-forward (MF$)<br />
request to the file with index .<br />
Symbolic Name: fp_err_bad_io_mf<br />
2006 Unexpected I/O status was returned by a move-backward (MB$)<br />
request to the file with index .<br />
Symbolic Name: fp_err_bad_io_mb<br />
2007 Unexpected I/O status was returned by a forward-space-file<br />
(FSF$) request to the file with index .<br />
Symbolic Name: fp_err_bad_io_fsf<br />
2008 Unexpected I/O status was returned by a backward-space-file<br />
(BSF$) request to the file with index .<br />
Symbolic Name: fp_err_bad_io_bsf<br />
2009 Unexpected I/O status was returned by a rewind (REW$)<br />
request to the file with index .<br />
Symbolic Name: fp_err_bad_io_rew<br />
2010 Unexpected I/O status was returned by a release (REL$) request<br />
to the file with index .<br />
Symbolic Name: fp_err_bad_io_rel<br />
7830 9796–013 A–21
Error Messages<br />
2011 Unexpected I/O status was returned by a write (W$) request to<br />
the file with index .<br />
Symbolic Name: fp_err_bad_io_w<br />
2012 Unexpected I/O status was returned by a gather-write (GW$)<br />
request to the file with index .<br />
Symbolic Name: fp_err_bad_io_gw<br />
2013 Unexpected I/O status was returned by a multiple-request (MR$)<br />
read-backward (RB$) request to the file with index .<br />
Symbolic Name: fp_err_bad_io_mr_rb<br />
2014 Unexpected I/O status was returned by a multiple-request (MR$)<br />
write (W$) request to the file with index .<br />
Symbolic Name: fp_err_bad_io_mr_w<br />
2015 Unexpected I/O status was returned by a write-end-of-file<br />
(WEF$) request to the file with index .<br />
Symbolic Name: fp_err_bad_io_wef<br />
2016 Unexpected I/O status was returned by a mode set (MS$)<br />
request to the file with index .<br />
Symbolic Name: fp_err_bad_io_ms<br />
2017 Unexpected I/O status was returned by a set mode (SM$)<br />
request to the file with index .<br />
Symbolic Name: fp_err_bad_io_sm<br />
2018 Unexpected I/O status was returned by a read block-id before<br />
write (RBIDW$) request to the file with index .<br />
Symbolic Name: fp_err_bad_io_rbidw<br />
2019 Unexpected I/O status was returned by a read block-id (RBKID$)<br />
request to the file with index .<br />
Symbolic Name: fp_err_bad_io_rbkid<br />
2020 Unexpected I/O status was returned by a locate block-id (LBLK$)<br />
request to the file with index .<br />
Symbolic Name: fp_err_bad_io_lblk<br />
2021 Unexpected I/O status was returned by a file update<br />
wait/synchronize (FSAFE$) request to the file with index .<br />
Symbolic Name: fp_err_bad_io_fsafe<br />
A–22 7830 9796–013
Error Messages<br />
2022 The Words_Transferred value returned by a scatter-read (SCR$) I/O request<br />
was different than PCFP expected for the file with index .<br />
Symbolic Name: fp_err_bad_word_count_scr<br />
2023 The Words_Transferred value returned by a gather-write (GW$) I/O request was<br />
different than PCFP expected for the file with index .<br />
Symbolic Name: fp_err_bad_word_count_gw<br />
2024 The Words_Transferred value returned by a multiple-request (MR$) I/O request<br />
was different than PCFP expected for the file with index .<br />
Symbolic Name: fp_err_bad_word_count_mr<br />
A.2.3. Execution Errors Other than I/O Errors—All File Types<br />
2101 The file is not or cannot be assigned as readable.<br />
Symbolic Name: fp_err_unreadable_file<br />
2102 The file is not or cannot be assigned as writable.<br />
Symbolic Name: fp_err_unwriteable_file<br />
2103 The source file and the destination file are the same file and the requested<br />
function does not allow them to be the same file.<br />
Symbolic Name: fp_err_same_files<br />
2120 Error status was returned by the ER INFO$ function MEDTYP$<br />
for the file with index .<br />
Symbolic Name: fp_err_bad_info_medtyp<br />
2121 Error status was returned by the ER INFO$ function INFILE$ for<br />
the file with index .<br />
Symbolic Name: fp_err_bad_info_infile<br />
2122 Error status was returned by the ER INFO$ function FFILEX$ for<br />
the file with index .<br />
Symbolic Name: fp_err_bad_info_ffilex<br />
2123 Error status was returned by the ER INFO$ function FBLKSX$<br />
for the file with index .<br />
Symbolic Name: fp_err_bad_info_fblksx<br />
7830 9796–013 A–23
Error Messages<br />
2124 Error status was returned by the ER INFO$ function FEQP$ for<br />
the file with index .<br />
Symbolic Name: fp_err_bad_info_feqp<br />
2125 Error status was returned by the ER INFO$ function ASGCNT$<br />
for the file with index .<br />
Symbolic Name: fp_err_bad_info_asgcnt<br />
2126 Error status was returned by the ER INFO$ function FREELX$<br />
for the file with index .<br />
Symbolic Name: fp_err_bad_info_freelx<br />
2127 Error status was returned by the ER INFO$ function LNAME$ for<br />
the file with index .<br />
Symbolic Name: fp_err_bad_info_lname<br />
2128 Error status was returned by the ER INFO$ function EQUIP$ for<br />
the file with index .<br />
Symbolic Name: fp_err_bad_info_equip<br />
2129 Error status was returned by the ER INFO$ function MODE$ for<br />
the file with index .<br />
Symbolic Name: fp_err_bad_info_mode<br />
2130 Error status was returned by the ER INFO$ function RING$ for<br />
the file with index .<br />
Symbolic Name: fp_err_bad_info_ring<br />
2131 Error status was returned by ER FITEM$ for the file with index<br />
.<br />
Symbolic Name: fp_err_bad_fitem<br />
2132 Information returned by FITEM$ indicated that the temporary file with index<br />
was not assigned to the run.<br />
Symbolic Name: fp_err_temp_no_equip<br />
A FITEM$ equipment code of 00, meaning not assigned was returned for a<br />
temporary file. This is logically inconsistent, since a temporary file only exists<br />
while it is assigned to a run.<br />
A–24 7830 9796–013
Error Messages<br />
2136 Unexpected error status was returned by ER SUVAL$.<br />
Symbolic Name: fp_err_bad_suval<br />
The error status is from S6 of word 0 of the SUVAL$ function packet. Refer to<br />
the Security Administration for ClearPath OS 2200 Help for interpretation of the<br />
status.<br />
2137 Unexpected function return status was returned by ER SUVAL$.<br />
Symbolic Name: fp_err_bad_suval_func<br />
The function return status is from T2 of word 010, 011 or 012 of a format 1<br />
SUVAL$ function packet or from T2 of word 012, 013 or 014 of a format 2<br />
SUVAL$ function packet. Refer to the Security Administration for ClearPath OS<br />
2200 Help for interpretation of the status.<br />
2141 System Error: PCFP detected an invalid Lead Item in the Master File Directory.<br />
Symbolic Name: fp_err_bad_mfd_lead_item<br />
The identifier code for the Lead Item, which was read from the Master File<br />
Directory, is not an identifier code for a Lead Item. It is likely that at least part<br />
of the Master File Directory has been corrupted.<br />
2142 System Error: PCFP detected an invalid Main Item in the Master File Directory.<br />
Symbolic Name: fp_err_bad_mfd_main_item<br />
The identifier code for the Main Item, which was read from the Master File<br />
Directory, is not an identifier code for a Main Item. It is likely that at least part<br />
of the Master File Directory has been corrupted.<br />
2143 System Error: PCFP detected an invalid Shared Item in the Master File<br />
Directory.<br />
Symbolic Name: fp_err_bad_mfd_shared_item<br />
The identifier code for the Shared Item, which was read from the Master File<br />
Directory, is not an identifier code for a Shared Item. It is likely that at least part<br />
of the Master File Directory has been corrupted.<br />
2144 System Error: PCFP detected invalid tape file information in the Program<br />
Control Table (PCT).<br />
Symbolic Name: fp_err_bad_pct_tape_info<br />
7830 9796–013 A–25
Error Messages<br />
2145 System Error: PCFP detected invalid or inconsistent information in the Name<br />
Section portion of the Program Control Table (PCT).<br />
Symbolic Name: fp_err_bad_pct_name_section<br />
This error is detected by the ACQ_FILE_INFO and ACQ_FILE_LIST functions,<br />
which directly examine the Program Control Table (PCT). This error can occur if<br />
the calling program is multi-activity and if more than one activity is calling PCFP<br />
functions or making other facilities requests that add internal or external<br />
filenames to the run (@USE or @ASG) or that remove internal or external<br />
filenames from the run (@FREE). It can also occur if the PCT Name Section of<br />
the run calling PCFP has overflowed or is close to overflowing.<br />
2151 System Error: Unrecognized equipment mnemonic was returned<br />
by the ER INFO$ function FEQP$ for the file with index .<br />
Symbolic Name: fp_err_unknown_equip_mnemonic<br />
Although the equipment mnemonic is printed in octal, it should be interpreted<br />
as Fieldata.<br />
2160 The file with index is not a cataloged file, but the called function<br />
requires such a file.<br />
Symbolic Name: fp_err_not_cataloged<br />
2161 The file with index is not a mass storage file, but the called<br />
function requires such a file.<br />
Symbolic Name: fp_err_not_ms<br />
2162 The file with index is not a sector-addressable mass storage file,<br />
but the called function requires such a file.<br />
Symbolic Name: fp_err_not_sector_ms<br />
2166 Your run does not have sufficient privileges to perform the requested operation.<br />
Symbolic Name: fp_err_not_privileged<br />
2171 PCFP Internal Error<br />
Symbolic Name: fp_err_sort_err<br />
2175 The name change could not be completed for this shared file because the<br />
name change capability is not available on all hosts or because the file sharing<br />
version is not Network file sharing.<br />
Symbolic Name: fp_err_sharing_incompatibility<br />
A–26 7830 9796–013
Error Messages<br />
2176 The name change could not be completed because a file with the requested<br />
qualifier and file name already exists.<br />
Symbolic Name: fp_err_new_name_exists<br />
2177 The name change could not be completed because one or more files of the<br />
F-cycle series are either unloaded or are on a symbiont queue.<br />
Symbolic Name: fp_err_unloaded_or_on_queue<br />
2178 The name change could not be completed for this removable disk file because<br />
it resides on or spans a pack that is in the DN,PACK state.<br />
Symbolic Name: fp_err_removable_pack_down<br />
2181 PCFP did not make the requested change, because fewer F-cycles would be<br />
retained than currently exist, and the function packet indicated that no<br />
currently-existing F-cycles are to be deleted.<br />
Symbolic Name: fp_err_too_many_f_cycles<br />
2182 PCFP did not make the requested change, because the change requires<br />
deletion of F-cycle +0 without eliminating the entire F-cycle series.<br />
Symbolic Name: fp_err_f_cycle_conflict<br />
PCFP issues this error if:<br />
• The F-cycle series contains a file that is to-be-cataloged with an absolute<br />
F-cycle number above that of F-cycle +0 of the series<br />
• PCFP needs to delete F-cycle +0 in order to perform the change<br />
The file to-be-cataloged can be assigned either by your run or by another run.<br />
PCFP also issues this error if:<br />
• The file identifier you specified contains an internal file name<br />
• The internal file name is attached to a specific F-cycle of the F-cycle series<br />
• PCFP needs to delete this F-cycle in order to perform the change<br />
For this function, you must not specify an internal file name attached to a<br />
specific F-cycle.<br />
2183 PCFP did not make the requested change, because the change requires the<br />
deletion of a file that is currently on a symbiont queue. The absolute F-cycle of<br />
the file on the symbiont queue is .<br />
Symbolic Name: fp_err_f_cycle_symmed<br />
7830 9796–013 A–27
Error Messages<br />
2184 PCFP did not make the requested change, because the change requires the<br />
deletion of a file that cannot be assigned exclusively to your run. The absolute<br />
F-cycle of the file that cannot be assigned exclusively to your run is<br />
.<br />
Symbolic Name: fp_err_cant_asg_f_cycle<br />
2185 PCFP did not make the requested change, because the change requires the<br />
deletion of a file that PCFP could not delete. The absolute F-cycle of the file<br />
that could not be deleted is .<br />
Symbolic Name: fp_err_cant_delete_f_cycle<br />
The item F_Cycles_Deleted in the function packet indicates the number of<br />
other files in the same F-cycle series (if any) that were deleted successfully<br />
while PCFP attempted to perform the requested change.<br />
2188 PCFP did not make the requested change, because the change requires the<br />
EXEC security features to be configured, and they are not configured.<br />
Symbolic Name: fp_err_security_not_configured<br />
2191 System Error: PCFP is unable to create the data bank it requires to do its basic<br />
mode processing.<br />
Symbolic Name: fp_err_cant_make_bank<br />
2192 System Error: PCFP is unable to release the data bank it created to do its basic<br />
mode processing.<br />
Symbolic Name: fp_err_cant_free_bank<br />
A–28 7830 9796–013
A.2.4. Execution Errors Other than I/O Errors—<br />
Sequential-Access Files<br />
Error Messages<br />
2201 A track sequence number error was detected while reading the source file.<br />
Symbolic Name: fp_err_seq_num_err<br />
Execution of the function was terminated, as requested by the value of FALSE<br />
for Process_Track_Seq_Errors in the function packet. The sequence number of<br />
the track causing the error can be found in item Loc_First_Track_Seq_Error in<br />
the function packet. This error frequently indicates invalid or corrupted data on<br />
the tape file.<br />
2202 A checksum error was detected while reading the source file.<br />
Symbolic Name: fp_err_checksum_err<br />
Execution of the function was terminated, as requested by the value FALSE for<br />
Process_Checksum_Errors in the function packet. The sequence number of<br />
the block causing the error can be found in item Loc_First_Checksum_Error in<br />
the function packet. This error frequently indicates invalid or corrupted data on<br />
the tape file.<br />
2205 The copy operation could not be performed, because the source file is written<br />
in a format not compatible with the requested format for the destination file.<br />
Symbolic Name: fp_err_format_incompat<br />
2206 PCFP Internal Error<br />
Symbolic Name: fp_err_incompat_blocksize<br />
The copy operation could not be performed, because the block size<br />
requirements of the files involved in the copy operation are not compatible.<br />
Currently, this error cannot be issued, since no combination of file types now<br />
handled by PCFP is incompatible in this fashion.<br />
2211 The source tape file was written in FURPUR format which does not match the<br />
format specified in the function packet.<br />
Symbolic Name: fp_err_wrong_format_furpur<br />
2212 The source tape file was written in SDF format which does not match the<br />
format specified in the function packet.<br />
Symbolic Name: fp_err_wrong_format_sdf<br />
2213 The source tape file was written in FAS1R1 format which does not match the<br />
format specified in the function packet.<br />
Symbolic Name: fp_err_wrong_format_fas1r1<br />
2214 The source tape file was written in FAS2R1 format which does not match the<br />
format specified in the function packet.<br />
Symbolic Name: fp_err_wrong_format_fas2r1<br />
7830 9796–013 A–29
Error Messages<br />
2215 The format of the logical file on the source tape file could not be recognized by<br />
PCFP.<br />
Symbolic Name: fp_err_unknown_format<br />
2216 The source tape file is a conditioned file. The site is not authorized to access<br />
the file.<br />
Symbolic Name: fp_err_conditioned_file.<br />
The source tape file is a conditioned file created by SOLAR. Individual files on<br />
a conditioned tape can only be copied if the keys contained in the file match<br />
keys that the site has installed. This error code indicates that the site does<br />
not have installed the keys that match this file. The file is not copied.<br />
2221 The requested operation was terminated because the source tape file is<br />
positioned at a logical file fragment continued from another volume.<br />
Symbolic Name: fp_err_continuation_fragment<br />
You cannot copy the current logical file from the source tape, because the<br />
initial portion of this logical file is on another volume.<br />
2222 The descriptor for the logical file on the source tape file is badly formed.<br />
Symbolic Name: fp_err_ill_formed_desc<br />
2223 A swap of the source tape file was attempted and the logical file descriptor<br />
found on the continued fragment of the logical file does not indicate a<br />
continued-file fragment as it should.<br />
Symbolic Name: fp_err_bad_continuation_desc<br />
2230 The specified block size exceeds the maximum for a destination file. The<br />
largest block size that can be written to the destination tape file is<br />
words.<br />
Symbolic Name: fp_err_block_size_too_big<br />
The destination tape file has a limit on the size of the physical blocks that can<br />
be written to it. The block size specified in the function packet exceeds that<br />
limit.<br />
2231 The block size specified in the function packet is not legal for the format of the<br />
file to be written to the destination file.<br />
Symbolic Name: fp_err_illegal_block_size<br />
2232 The block size you specified in the function packet does not match the block<br />
size with which the source file was written.<br />
Symbolic Name: fp_err_wrong_block_size<br />
If a block size of zero is specified in the function packet, PCFP will copy the<br />
file regardless of the block size with which it was written.<br />
2233 The source tape file cannot be read because it is positioned at its logical end.<br />
Symbolic Name: fp_err_at_logical_end<br />
A–30 7830 9796–013
There are no further logical files on the tape. You must move the tape<br />
backward before you can read another logical file from the tape.<br />
Error Messages<br />
2235 The destination tape file is not positioned immediately following an EOF mark.<br />
Symbolic Name: fp_err_not_after_eof<br />
The tape must be positioned immediately following an EOF mark before you<br />
can copy another logical file to it.<br />
2251 The tape could not be moved completely as you requested, because a swap<br />
would have been required, but Current_Vol_Only in the function packet was<br />
set to TRUE.<br />
Symbolic Name: fp_err_past_end_of_vol<br />
When Current_Vol_Only is set to TRUE, no reel swaps are to be done during<br />
the Move operation. The Move has been completed only to the end of the<br />
current volume, so that the tape has been positioned at the last logical file on<br />
that volume.<br />
2252 The end of the last volume of the tape file with index was<br />
encountered and extension of the file to another volume was prohibited.<br />
Symbolic Name: fp_err_swap_beyond_end<br />
PCFP did not attempt to extend the tape file to another volume because the<br />
value of On_End_of_File in the function packet was set to error.<br />
2253 PCFP Internal Error<br />
Symbolic Name: fp_err_supply_vol<br />
2254 PCFP Internal Error<br />
Symbolic Name: fp_err_verify_vol<br />
2255 PCFP Internal Error<br />
Symbolic Name: fp_err_caller_subr<br />
2257 The system operator aborted the attempted swap beyond the last volume of<br />
the tape file with index .<br />
Symbolic Name: fp_err_operator_aborted_swap<br />
The attempted swap was aborted due to operator key-in.<br />
2261 The caller subroutine called by PCFP to process the source file logical file<br />
descriptor returned an error code to PCFP indicating that it could not<br />
successfully complete its operation.<br />
Symbolic Name: fp_err_src_desc_decode<br />
2262 The caller subroutine called by PCFP to process the destination file logical file<br />
descriptor returned an error code to PCFP indicating that it could not<br />
successfully complete its operation.<br />
7830 9796–013 A–31
Error Messages<br />
Symbolic Name: fp_err_desc_subr_err<br />
2265 The caller subroutine called by PCFP to process the source file swap message<br />
returned an error code to PCFP indicating that it could not successfully<br />
complete its operation.<br />
Symbolic Name: fp_err_after_src_swap<br />
2266 The caller subroutine called by PCFP to process the destination file swap<br />
message returned an error code to PCFP indicating that it could not<br />
successfully complete its operation.<br />
Symbolic Name: fp_err_after_dest_swap<br />
2301 The source tape file could not be read because it has inconsistent block<br />
sizes. The number of words transferred () is not a multiple of<br />
the tape block size.<br />
Symbolic Name: fp_err_bad_blocking<br />
This error frequently indicates invalid or corrupted data on the tape file. Note<br />
that the tape block size for FURPUR format tape files (FORMAT = FURPUR)<br />
should be a multiple of 1,794 words (2 header words + 1,792 data words).<br />
2302 The source tape file could not be read because it has a badly formed track<br />
header.<br />
Symbolic Name: fp_err_bad_track_header<br />
This error frequently indicates invalid or corrupted data on the tape file.<br />
2303 The status returned on the read of the source tape file indicates that one or<br />
more words from a tape block were discarded because they did not fit in the<br />
provided buffer space.<br />
Symbolic Name: fp_err_data_truncated<br />
PCFP always provides enough buffer space to contain the expected size of<br />
the entire tape block for the format of the tape file being processed. This<br />
error indicates that a block larger than the expected size was read. This<br />
abnormal condition indicates invalid or corrupted data on the tape file or a<br />
hardware or microcode error.<br />
2304 The function could not be completed because the tape file with index<br />
does not allow backward movement.<br />
Symbolic Name: fp_err_no_backward_alwd<br />
2340 Unexpected status 11 with I/O status was returned by ER<br />
TLBL$ against the tape file with index .<br />
Symbolic Name: fp_err_bad_tlbl_io<br />
2341 Unexpected status was returned by ER TLBL$ against the tape<br />
file with index .<br />
Symbolic Name: fp_err_bad_tlbl<br />
A–32 7830 9796–013
Error Messages<br />
2342 Unexpected status was returned by ER TINTL$ against the<br />
tape file with index .<br />
Symbolic Name: fp_err_bad_tintl<br />
2343 Unexpected status was returned by ER TSWAP$ against the<br />
tape file with index .<br />
Symbolic Name: fp_err_bad_tswap<br />
2344 The function cannot be performed because of a previous Locate Block<br />
(LBLK$) I/O function against the tape file with index .<br />
Symbolic Name: fp_err_locate_block<br />
Tape files positioned with Locate Block are write inhibited, so the functions<br />
CLOSE_SAF, COPY_RAF_SAF and COPY_SAF_SAF (with the positioned tape<br />
as the destination file) are not allowed.<br />
2345 The requested tape positioning cannot be performed because fast tape<br />
access is not supported for this tape equipment type.<br />
Symbolic Name: fp_err_no_fast_tape_access<br />
2346 The requested tape positioning cannot be performed because your run does<br />
not have the privileges that are required for a Locate Block (LBLK$) I/O<br />
function.<br />
Symbolic Name: fp_err_no_locate_block_priv<br />
For systems with Fundamental Security (SENTRY_CONTROL FALSE), the<br />
caller must be running under the overhead account or the security officer<br />
account or must have SYS$*DLOC$ assigned to the run with the correct read<br />
and write keys. For systems with Security Option 1, 2, or 3<br />
(SENTRY_CONTROL TRUE), the special privileges<br />
bypass_tape_hdr1_read_checks (SSBHDR1RDCHK) and bypass_object_reuse<br />
(SSBYOBJREUSE) are required.<br />
A.2.5. Execution Errors Other than I/O Errors—Random-Access<br />
Files<br />
2501 The maximum size of the destination file is too small.<br />
Symbolic Name: fp_err_file_too_small<br />
The function was terminated when the destination file was filled to its<br />
maximum size.<br />
7830 9796–013 A–33
Error Messages<br />
2502 The file with index is not initially empty and the function packet<br />
indicates that it must be empty.<br />
Symbolic Name: fp_err_dest_not_empty<br />
The COPY_OMN_ELT_RAF, COPY_RAF_RAF, and COPY_SAF_RAF functions<br />
return this error message when Prevent_Overcopy is TRUE and the<br />
destination file is not empty. To complete the function, erase the destination<br />
file with the ERS_RAF function or set Prevent_Overcopy to FALSE.<br />
The COPY_SYM_ELT_RAF function returns this error message when Action is<br />
must_be_empty (1) and the destination file is not empty. To complete the<br />
function, erase the destination file with the ERS_RAF function or set Action to<br />
overcopy (0).<br />
The CHG_FILE function returns this error message when Init_Program_File is<br />
other than none (0) and the file is already a program file. To complete the<br />
function, erase the file with the ERS_RAF function or set Init_Program_File to<br />
none (0).<br />
The COPY_ELT, COPY_RAF_OMN_ELT, and COPY_RAF_SYM_ELT functions<br />
return this error message when Init_Dest_File is other than none (0) and the<br />
destination file is already a program file. To complete the function erase the<br />
destination file with the ERS_RAF function or set Init_Dest_File to none (0).<br />
2503 The file or element being copied contains a hole (unallocated area) within the<br />
text.<br />
Symbolic Name: fp_err_hole_in_file<br />
Elements or files that are to become elements must not contain a hole<br />
(unallocated area) within the text.<br />
2504 File sharing is down. The use of shared files is not currently allowed.<br />
Symbolic Name: fp_err_file_sharing_down<br />
2511 System Error: Unexpected status was returned by the DREAD$<br />
function of ER MSCON$ while attempting to retrieve the directory items<br />
associated with the file with index .<br />
Symbolic Name: fp_err_bad_dread<br />
2512 System Error: Unexpected status was returned by the DIRID$<br />
function of ER MSCON$ while attempting to retrieve the directory-id names<br />
for the system.<br />
Symbolic Name: fp_err_bad_dirid<br />
2513 System Error: Unexpected status was returned by the EXIST$<br />
function of ER MSCON$ while attempting to retrieve the directory items<br />
associated with the file submitted to PCFP.<br />
Symbolic Name: fp_err_bad_exist<br />
A–34 7830 9796–013
Error Messages<br />
2514 System Error: Unexpected status was returned by the MULTI$<br />
function of ER MSCON$ while attempting to change the attributes associated<br />
with the file submitted to PCFP.<br />
Symbolic Name: fp_err_bad_multi<br />
2515 System Error: Unexpected Status was returned by the DCYC$<br />
function of ER MSCON$ while attempting to change the F-cycle range of the<br />
file submitted to PCFP.<br />
Symbolic Name: fp_err_bad_dcyc<br />
2516 System Error: Unexpected Status was returned by the DKEY$<br />
function of ER MSCON$ while attempting to change the read/write keys of<br />
the file submitted to PCFP.<br />
Symbolic Name: fp_err_bad_dkey<br />
2517 System Error: Unexpected status was returned by the DBITS$<br />
function of ER MSCON$ while attempting to change the security attributes<br />
associated with the file submitted to PCFP.<br />
Symbolic Name: fp_err_bad_dbits<br />
2518 System Error: Unexpected status was returned by the<br />
NAMCHG$ function of ER MSCON$ while attempting to change the name of<br />
the file submitted to PCFP.<br />
Symbolic Name: fp_err_bad_namchg<br />
2519 System Error: Unexpected I/O error status was returned by the<br />
NAMCHG$ function of ER MSCON$ while attempting to change the name of<br />
the file submitted to PCFP.<br />
Symbolic Name: fp_err_bad_namchg_io<br />
7830 9796–013 A–35
Error Messages<br />
2520 Device Area Descriptor (DAD) table sector number is too large<br />
for the DREAD$ function of ER MSCON$.<br />
Symbolic Name: fp_err_dad_sector_too_large<br />
COPY_RAF_RAF and COPY_RAF_SAF read DAD tables for cataloged mass<br />
storage source files to improve the efficiency of copy operations. The source<br />
file has too many DAD sectors and cannot be completely copied to the<br />
destination file. The function packet item Amount_Copied contains the<br />
number of words that were correctly copied when this error was detected.<br />
2521 System Error: Unexpected Status was returned by ERSUMOD$<br />
while attempting to change the security attributes associated with the file<br />
submitted to PCFP.<br />
Symbolic Name: fp_err_bad_sumod<br />
2522 The value specified for Clearance_Level in the function packet does not lie in<br />
the file's clearance level range.<br />
Symbolic Name: fp_err_cl_level_out_of_range<br />
2523 An Access Control Record (ACR) whose name matches the value specified for<br />
ACR_Name in the function packet and which is owned by your user-id does<br />
not exist.<br />
Symbolic Name: fp_err_unknown_acr_name<br />
2524 Attributes of the new File_Owner_User_Id and the file are not compatible.<br />
Symbolic Name: fp_err_owner_file_not_compat<br />
2525 An ACR cannot be attached to the file because it is shared and unowned.<br />
Symbolic Name: fp_err_bad_shared_acr<br />
2526 The owner of the ACR does not match the owner of the file.<br />
Symbolic Name: fp_err_acr_file_owner_mismatch<br />
The owner of the ACR must match the owner of the file in order for the ACR<br />
to be attached to the file.<br />
2527 A user id which matches the value specified for File_Owner_User_Id in the<br />
function packet does not exist.<br />
Symbolic Name: fp_err_unknown_file_owner<br />
2528 You cannot change the security attributes of a file you do not own.<br />
Symbolic Name: fp_err_not_file_owner<br />
Only the owner of a file (or a user given special privileges by the security<br />
administrator) can change the owner, privacy, ACR, or clearance level of that<br />
file.<br />
A–36 7830 9796–013
2531 System Error: An unexpected status was returned by<br />
ERCONFIG$ while attempting to perform the requested function.<br />
Symbolic Name: fp_err_bad_Config<br />
Error Messages<br />
A.2.6. Execution Errors Other than I/O Errors—Program Files<br />
2601 The file with index is not a program file and the called function<br />
requires a program file.<br />
Symbolic Name: fp_err_not_pf<br />
2602 The file with index is an empty file and the called function<br />
requires a non-empty program file.<br />
Symbolic Name: fp_err_empty_file<br />
2603 The function could not be completed because the program file table of<br />
contents for table does not have enough open entries.<br />
Symbolic Name: fp_err_toc_space_too_small<br />
Completion of the function requires more table entries than the program file<br />
table of contents can contain.<br />
Table 1 is the element table.<br />
Table 2 is the MASM procedure table.<br />
Table 3 is the COBOL procedure table.<br />
Table 4 is the FORTRAN/PLUS procedure table.<br />
Table 5 is the relocatable entry point table.<br />
The maximum number of entries for each table depends on the table type and<br />
whether this is a standard program file or a large program file. You may be<br />
able to complete the function by removing deleted elements from the<br />
program file with the PACK_PF function.<br />
2604 The function did not create an element because the destination file already<br />
contains an element with the same name, version, and type. The sequence<br />
of the duplicate element is .<br />
Symbolic Name: fp_err_elt_conflict<br />
2605 The operation could not be performed because the program file with index<br />
is missing all or part of its table of contents.<br />
Symbolic Name: fp_err_pf_toc_truncated<br />
2606 The operation could not be performed because the program file with index<br />
is missing all or part of its element text.<br />
Symbolic Name: fp_err_elt_text_truncated<br />
2607 Text size of words exceed the maximum of 7,340,004 words<br />
allowed for a PF or LPF program file element.<br />
Symbolic Name: fp_err_elt_text_too_large<br />
7830 9796–013 A–37
Error Messages<br />
This error is returned when attempting to create an element in a PF or LPF.<br />
The maximum element text size for a PF or LPF program file element is<br />
0777777 sectors (18-bit octal value) or 262,143 sectors (decimal value). These<br />
values can be converted to a decimal value of 7,340,004 words.<br />
2608 Text size of words exceeds the maximum allowed for an LEPF<br />
program file element.<br />
Symbolic Name: fp_err_lepf_elt_text_too_large<br />
This error is returned when attempting to create an element in an LEPF. The<br />
maximum element text size for an LEPF program file element is dependent on<br />
the element type. In all cases, the size must be less than the maximum file<br />
size (262,143 positions or 16,777,152 tracks or 1,073,737,728 sectors or<br />
30,064,656,384 words) minus the size of the standard program file table of<br />
contents (28 tracks or 1,792 sectors or 50,176 words) or the size of the large<br />
program file table of contents (629 tracks or 40,256 sectors or 1,127,168<br />
words).<br />
2609 The LEPF program file element with sequence number has an<br />
illegal element text length granularity value.<br />
Symbolic Name: fp_err_bad_granularity<br />
This error is returned when reading an LEPF element. For the indicated<br />
element, the 2-bit element text length granularity field (element table item<br />
word 3, bits 1 and 2) has an illegal value of 3.<br />
2610 The LEPF program file element with sequence number has a<br />
text size that exceeds the maximum.<br />
Symbolic Name: fp_err_bad_elt_text_length<br />
This error is returned when reading an LEPF element. PCFP converts the<br />
element text length, which is in sectors, tracks, or positions as indicated by<br />
the element text length granularity, to a text size value that is in number of<br />
words. For the indicated element, the text size exceeded the largest positive<br />
value that can be stored in a 36-bit word. The largest legal value is<br />
0377777777777 or 34,359,738,367 words. Note that this value is actually<br />
somewhat larger than the 30,064,606,208 words that are currently possible<br />
for the largest possible element in the largest possible standard program file<br />
or the 30,063,479,040 words that are currently possible for the largest<br />
possible element in the largest possible large program file.<br />
2611 Symbolic procedure, relocatable and absolute elements cannot be copied to<br />
an LEPF.<br />
Symbolic Name: fp_err_bad_lepf_elt_type<br />
Symbolic procedure elements (symbolic subtypes 29, 64, 65, and 66),<br />
relocatable elements, or absolute elements cannot be copied to an LEPF<br />
destination file.<br />
A–38 7830 9796–013
Error Messages<br />
2612 The element with the sequence number specified is not correctly linked by<br />
element name, element version or element type.<br />
Symbolic Name: fp_err_elt_link_type<br />
The element sequence number links contained in the program file pointer<br />
table and the element entries are incorrect or inconsistent. The program file<br />
table of contents should be rebuilt with the PCFP PACK_PF function to correct<br />
the links.<br />
2650 The Basic Service Package (BSP) detected a program file format error with the<br />
error code for the file with index .<br />
Symbolic Name: fp_err_bsp_pf_format_err<br />
The Basic Service Package routine called by PCFP detected an error in the<br />
format of the program file and was unable to continue. Refer to the SYSLIB<br />
<strong>Programming</strong> <strong>Reference</strong> <strong>Manual</strong> for the interpretation of the displayed error<br />
code.<br />
2651 The program file with index does not have a recognizable table<br />
of contents.<br />
Symbolic Name: fp_err_bad_pf_toc<br />
Program-file functions cannot be used on this file.<br />
2652 The program file contains duplicate elements (same name, version, and type).<br />
The sequence number of the second element of the duplicate pair is<br />
.<br />
Symbolic Name: fp_err_duplicate_elt<br />
A valid program file does not contain duplicate elements. This file cannot be<br />
packed until you delete the duplicate elements.<br />
2653 The table of contents of the program file indicates that the text of two<br />
elements in the file overlap. The sequence number of one of these elements<br />
is .<br />
Symbolic Name: fp_err_overlapped_elts<br />
A valid program file does not contain overlapping elements. This file cannot<br />
be packed as doing so might destroy the text of one or more elements in the<br />
file.<br />
2654 An unexpected error was returned by the Basic Service<br />
Package (BSP).<br />
Symbolic Name: fp_err_bsp_err<br />
A Basic Service Package routine is called by PCFP for program file<br />
manipulations. This error may indicate corruption of the data in the program<br />
file. Refer to the SYSLIB <strong>Programming</strong> <strong>Reference</strong> <strong>Manual</strong> for its<br />
interpretation.<br />
7830 9796–013 A–39
Error Messages<br />
2655 An unexpected I/O error was returned by the Basic Service<br />
Package (BSP).<br />
Symbolic Name: fp_err_bsp_io_err<br />
A Basic Service Package routine called by PCFP for program file manipulations<br />
detected an I/O error. This error may indicate corruption of the data in the<br />
program file.<br />
2656 System Error: An undefined error code was returned by the<br />
Basic Service Package (BSP).<br />
Symbolic Name: fp_err_bsp_illegal_err<br />
A Basic Service Package routine called by PCFP for certain program file<br />
manipulations returned an undefined or illegal error code.<br />
2657 PCFP Internal Error: <br />
Symbolic Name: fp_err_bsp_caller_err<br />
The Basic Service Package detected an error in the calling sequence, buffer<br />
size, or buffer contents supplied by PCFP. This indicates a PCFP logic error.<br />
Refer to the SYSLIB <strong>Programming</strong> <strong>Reference</strong> <strong>Manual</strong> for the interpretation of<br />
the displayed error code.<br />
2658 PCFP Internal Error<br />
Symbolic Name: fp_err_bsp_no_find<br />
A logic problem was detected within PCFP, concerned with handling of a<br />
Basic Service Package (BSP) status.<br />
2659 System Error: Installation of a more recent SYSLIB level is required. The<br />
referenced SYSLIB Basic Service Package (BSP) does not support all of the<br />
functionality required by PCFP.<br />
Symbolic Name: fp_err_bad_syslib_level<br />
Information returned by the SYSLIB BSP$ Read File Table Index (RFTI$$)<br />
function indicates that the level of SYSLIB referenced does not support the<br />
functionality required by the PCFP program file functions. Refer to the<br />
ClearPath IX and 2200 Series Software Planning and Migration Overview<br />
release level 7.0 for your installed ClearPath or 2200 system release level to<br />
determine the level of SYSLIB that corresponds to this level of PCFP.<br />
2661 The element with the name and version you specified, and the type required<br />
by the function, does not exist in the program file.<br />
Symbolic Name: fp_err_nonexistent_elt<br />
2662 The symbolic cycle specified does not exist in the element specified.<br />
Symbolic Name: fp_err_nonexistent_cycle<br />
A–40 7830 9796–013
Error Messages<br />
2663 The sequence number specified does not exist in the program file. The<br />
largest sequence number in the file is .<br />
Symbolic Name: fp_err_nonexistent_seq_num<br />
2672 System Error: The Run-Time library routines used by the Linking System have<br />
not been installed.<br />
Symbolic Name: fp_err_ls_missing_bank<br />
2673 System Error: A bank containing the Linking System (LS) routines called by<br />
PCFP to either prep or retrieve object module entry points has not been<br />
installed.<br />
Symbolic Name: fp_err_no_ls_bank<br />
2674 Unexpected status was returned by a Linking System (LS)<br />
routine which was called by PCFP to operate on a program file.<br />
Symbolic Name: fp_err_ls_err<br />
This error might indicate corruption of the data in the program file.<br />
2675 Unexpected I/O error was returned by a Linking System(LS)<br />
routine called by PCFP to operate on a program file.<br />
Symbolic Name: fp_err_ls_io_err<br />
This error often indicates that the file is not large enough to contain the object<br />
module entry point table. You should expand the size of the file you want<br />
prepped. In some cases, this error might indicate corruption of the data in the<br />
program file.<br />
2676 System Error: An undefined error status was returned by a<br />
Linking System (LS) routine which was called by PCFP to operate on a<br />
program file.<br />
Symbolic Name: fp_err_ls_illegal_err<br />
2677 System Error: Linking System (LS) Internal Error: <br />
Symbolic Name: fp_err_ls_internal_err<br />
A Linking System (LS) routine called by PCFP to operate on the program file<br />
returned an internal error type.<br />
2678 Unexpected I/O error was returned by a Linking System (LS)<br />
routine called by PCFP to operate on a program file while it attempted to write<br />
to a temporary file.<br />
Symbolic Name: fp_err_ls_io_temp_err<br />
This error occurred while the Linking System was collecting information about<br />
the entry points in the program file.<br />
2701 The SDF file or element being operated on does not contain legal SDF text.<br />
The text contains no Label Control Record.<br />
Symbolic Name: fp_err_bad_sdf_label_record<br />
7830 9796–013 A–41
Error Messages<br />
2702 The SDF file or element being operated on contains a type of SDF text that<br />
the PCFP function cannot handle.<br />
Symbolic Name: fp_err_bad_sdf_type<br />
The operation requested requires a symbolic element containing text with<br />
symbolic element cycles. This implies that the text type of the element must<br />
be general-symbolic (’S’). The element you attempted to operate on contains<br />
a different type of symbolic text.<br />
2706 PCFP could not copy the SDF file or symbolic element because it contains no<br />
SDF end-of-text control record.<br />
Symbolic Name: fp_err_no_sdf_eof<br />
2721 The relocatable element with sequence number contains a<br />
relocatable preamble with an invalid index and/or count for the element's<br />
relocatable entry point table.<br />
Symbolic Name: fp_err_bad_rel_preamble<br />
To create a program file Relocatable Element Entry Point Table (REEPT), the<br />
PREP_PF function must be able to correctly read the entry point tables for<br />
each relocatable element that is not deleted. The entry point table could not<br />
be read for the element indicated in the message. The entry point table index<br />
and the entry point table item count indicate that some or all of the entry point<br />
table is beyond the end of the relocatable preamble. This error could indicate<br />
that the relocatable text for this element has been corrupted. This element<br />
must be deleted with the PCFP DELETE_ELT function or the FURPUR<br />
@DELETE,R command before the REEPT can be created with the PCFP<br />
PREP_PF function or the FURPUR @PACK,P or @PREP commands.<br />
Note that there may be additional relocatable elements beyond the one<br />
indicated that also have invalid entry point tables.<br />
A.2.7. Errors Associated with Assigning and Freeing Files<br />
3001 The file with index could not be assigned and the error<br />
returned by the attempted assign was .<br />
Symbolic Name: fp_err_cant_asg<br />
3002 The file with index could not be exclusively assigned and the<br />
error returned by the attempted exclusive assign was .<br />
Symbolic Name: fp_err_cant_asg_x<br />
3003 The error was returned while trying to attach an internal<br />
name (@USE) to the file with index .<br />
Symbolic Name: fp_err_cant_attach_use<br />
3004 The file with index does not exist.<br />
Symbolic Name: fp_err_file_not_found<br />
The file is neither cataloged nor is it assigned to your run.<br />
A–42 7830 9796–013
Error Messages<br />
3005 The file with index could not be assigned with the AE<br />
options, because it is already assigned with the AY options.<br />
Symbolic Name: fp_err_file_state_wrong<br />
PCFP must assign the file with the AE options, but it was previously<br />
assigned with the AY options. Since these options are mutually exclusive,<br />
you must free the file before the requested function can be performed on<br />
the file.<br />
3006 The file with index cannot be assigned in the manner<br />
required by the function.<br />
Symbolic Name: fp_err_file_rw_inhibited<br />
The file was previously assigned with the AE or AY options, which prevents<br />
the file from being read from or written to. You must free the file before<br />
the requested function can be performed on the file.<br />
3010 The file with index could not be freed; the error returned by<br />
the attempted free was .<br />
Symbolic Name: fp_err_cant_free<br />
The file was assigned automatically by PCFP. The error occurred when<br />
PCFP attempted to free the file.<br />
3011 The file with index could not be deleted; the error returned<br />
by the attempted delete was .<br />
Symbolic Name: fp_err_cant_free_d<br />
The file was assigned automatically by PCFP. The error occurred when<br />
PCFP attempted to delete the file as required by the function.<br />
3012 The file could not be deleted, because it was on a symbiont queue.<br />
Symbolic Name: fp_err_file_on_sym_q<br />
The file must be removed from the symbiont queue before it can be<br />
deleted.<br />
3021 Error message number was returned while trying to assign<br />
the file SYS$DLOC$.<br />
Symbolic Name: fp_err_cant_asg_dloc<br />
PCFP attempted to assign this file automatically, since its assignment is<br />
required to perform the requested function.<br />
3031 Error message number was returned while trying to assign a<br />
temporary file that PCFP needs to complete the processing of the<br />
requested function.<br />
Symbolic Name: fp_err_cant_asg_temp<br />
3032 Error message number was returned while trying to free a<br />
temporary file that PCFP used to complete the processing of the requested<br />
function.<br />
7830 9796–013 A–43
Error Messages<br />
Symbolic Name: fp_err_cant_free_temp<br />
3033 The file submitted to the PACK_LPF function is not assigned and it is<br />
required that the file be assigned.<br />
Symbolic Name: fp_err_file_not_asgd<br />
3051 The file with index has an unknown equipment code<br />
, which is not handled by PCFP.<br />
Symbolic Name: fp_err_unknown_equip_code<br />
Although the equipment code is printed in octal, it should be interpreted as<br />
Fieldata.<br />
A–44 7830 9796–013
A.2.8. Errors Associated with the PACK_PF Function<br />
Error Messages<br />
The errors listed in this subsection can occur when using the copy method of the<br />
PACK_PF function. See 8.4 for additional information on the PACK_PF copy method.<br />
These error codes are returned when a PCFP function called by the copy method<br />
encounters an error.<br />
The errors listed in this subsection have an associated Sub_Error_Code and should be<br />
handled as described at the beginning of this appendix. For each error message, the<br />
“Error code = , auxiliary error code = , error file index =<br />
” is displayed only if an ELMS explanation level of 2 or greater is<br />
requested.<br />
3502 During a program file pack, the copy of the program file elements to the<br />
temporary intermediate file resulted in the following error:<br />
Error code = , auxiliary error code = , error file<br />
index = .<br />
Symbolic Name: fp_err_cant_copy_to_temp<br />
The COPY_ELT function was called by the PACK_PF function to copy the<br />
requested nondeleted elements and procedures from a program file that is<br />
being packed to a temporary intermediate file. In the process, it encountered<br />
and returned the error code and auxiliary error code shown in the error<br />
message and contained in the function packet Sub_Error_Code and<br />
Aux_Error_Code items.<br />
3503 During a program file pack, the copy of the temporary intermediate file back to<br />
the program file resulted in the following error:<br />
Error code = , auxiliary error code = , error file<br />
index = .<br />
Symbolic Name: fp_err_cant_copy_from_temp<br />
The COPY_RAF_RAF function was called by the PACK_PF function to copy the<br />
contents of the temporary intermediate file back to the program file being<br />
packed. In the process, it encountered and returned the error code and<br />
auxiliary error code shown in the error message and contained in the function<br />
packet Sub_Error_Code and Aux_Error_Code items.<br />
3504 During a program file pack, the clearing of the temporary intermediate file<br />
resulted in the following error:<br />
Error code = , auxiliary error code = , error file<br />
index = .<br />
Symbolic Name: fp_err_cant_clear_temp<br />
The ERS_RAF function was called by the PACK_PF function to zero-out the<br />
temporary intermediate file after the contents of that file had been copied back<br />
to the program file being packed. In the process, it encountered and returned<br />
the error code and auxiliary error code shown in the error message and<br />
contained in the function packet Sub_Error_Code and Aux_Error_Code items.<br />
3506 During a program file pack, the prepping of the program file resulted in the<br />
following error:<br />
Error code = , auxiliary error code = , error file<br />
7830 9796–013 A–45
Error Messages<br />
index = .<br />
Symbolic Name: fp_err_cant_prep<br />
The PREP_PF function was called by the PACK_PF function to prep a program<br />
file that was just packed. In the process, it encountered and returned the error<br />
code and auxiliary error code shown in the error message and contained in the<br />
function packet Sub_Error_Code and Aux_Error_Code items.<br />
A–46 7830 9796–013
Appendix B<br />
Summary of FURPUR Commands<br />
This appendix is not meant to be used as a FURPUR reference. The ECL and FURPUR<br />
<strong>Reference</strong> <strong>Manual</strong> is written for that purpose and contains the complete description of<br />
FURPUR commands and options.<br />
This appendix is meant to summarize all available FURPUR commands and to indicate<br />
the analogous PCFP function or functions, when applicable. In Table B–1 the FURPUR<br />
commands are presented alphabetically in the first column, generally in the same order<br />
that they appear in the ECL and FURPUR <strong>Reference</strong> <strong>Manual</strong>. The second column<br />
provides a brief description of the command; where applicable it also refers to notes that<br />
follow Table B–1. The third column provides the analogous PCFP function name or not<br />
available if there is no analogous PCFP function. The fourth column provides additional<br />
information on PCFP function packet fields that relate to the FURPUR command.<br />
The following abbreviations are used with FURPUR commands shown in the first column<br />
of Table B–1.<br />
file<br />
ms<br />
tape<br />
pf<br />
elt<br />
The name of a file. It is used as an abbreviation for the fully qualified file name.<br />
The name of a mass storage file; used when it is necessary to differentiate this file<br />
from a tape file.<br />
The name of a tape file; used when necessary to differentiate this file from a mass<br />
storage file.<br />
The name of a mass storage file that has been formatted as a standard program file<br />
or as a large program file.<br />
The name of a program file element. It is used as an abbreviation for the fully<br />
qualified file name and element name.<br />
7830 9796–013 B–1
Summary of FURPUR Commands<br />
SDF<br />
The name of mass storage file or a tape file that has been formatted as a system<br />
data format (SDF) file.<br />
Table B–1. Summary of FURPUR Commands<br />
FURPUR Command Description PCFP Function Packet Fields<br />
@CHG<br />
file/r1/w1.,file/r2/w2<br />
Change file read key,<br />
write key<br />
@CHG,F file.,spec Change file caching<br />
specifications<br />
CHG_FILE_KEYS READ_KEY=r2<br />
WRITE_KEY=w2<br />
Not available<br />
@CHG,N file1.,file2. Change file name CHG_FILE_NAME<br />
@CHG,P file. Set public mode CHG_FILE_SEC PRIVACY=PUBLIC<br />
@CHG,Q file. Set private mode CHG_FILE_SEC PRIVACY=PUBLIC<br />
@CHG,K file.,acr Set semiprivate mode CHG_FILE_SEC PRIVACY=<br />
SEMIPRIVATE<br />
ACR_NAME=acr<br />
@CHG,T file.<br />
@CHG,E file.<br />
Initialize large program<br />
file or large element<br />
program file<br />
@CHG,V file. Set read-only, clear<br />
write-only mode<br />
@CHG,W file. Set write-only, clear<br />
read-only modes<br />
@CHG,Z file. Clear read-only and<br />
write-only modes<br />
@CHG,AORS<br />
elt1,elt2<br />
@CLOSE<br />
tape1.[,tape2.,...]<br />
Change element,<br />
version names; see<br />
notes 1, 2, 3, and 4<br />
Close tapes and rewind;<br />
see notes 5 and 8<br />
@COPIN tape.,pf. Copy from element<br />
format tape to program<br />
file<br />
@COPOUT pf.,tape. Copy from program file<br />
to element format tape<br />
CHG_FILE INIT_PROGRAM_<br />
FILE<br />
CHG_FILE READ_ONLY=<br />
SET_ON<br />
WRITE_ONLY=<br />
SET_OFF<br />
CHG_FILE READ_ONLY=<br />
SET_OFF<br />
WRITE_ONLY=<br />
SET_ON<br />
CHG_FILE READ_ONLY=<br />
SET_OFF<br />
WRITE_ONLY=<br />
SET_OFF<br />
CHG_ELT<br />
CLOSE_SAF<br />
MOVE_SAF<br />
Not available<br />
Not available<br />
TYPE_OF_MOVE=<br />
TO_SAF_START<br />
CURRENT_VOL_<br />
ONLY=FALSE<br />
B–2 7830 9796–013
Summary of FURPUR Commands<br />
Table B–1. Summary of FURPUR Commands<br />
FURPUR Command Description PCFP Function Packet Fields<br />
Copy mass storage file to mass storage file<br />
@COPY ms.,ms. Copy mass storage file<br />
to mass storage file<br />
@COPY,AORS<br />
elt1,elt2<br />
@COPY,P pf1.,pf2.<br />
@COPY,F<br />
SDF1.,SDF2.<br />
Copy elements; see<br />
notes 1, 2, 3, 4, and 6<br />
Copy SDF file to SDF<br />
file<br />
@COPY,I SDF.,elt Copy SDF file to<br />
symbolic element<br />
@COPY,I elt,SDF. Copy symbolic element<br />
to SDF file<br />
@COPY,IO ms.,elt Copy mass storage file<br />
to omnibus element<br />
@COPY,IO elt,ms. Copy omnibus element<br />
to mass storage file<br />
@COPY ms.,tape. Unformatted copy of<br />
mass storage file to<br />
tape file<br />
COPY_RAF_RAF<br />
COPY_ELT<br />
Not available<br />
COPY_RAF_SYM_<br />
ELT<br />
COPY_SYM_ELT_<br />
RAF<br />
COPY_RAF_OMN_<br />
ELT<br />
COPY_OMN_ELT_<br />
RAF<br />
Copy mass storage file to tape file<br />
@COPY,B ms.,tape. Copy FORTRAN mass<br />
storage data file to tape<br />
file<br />
@COPY,F SDF.,tape. Copy SDF mass<br />
storage file to tape file<br />
@COPY,G ms.,tape. Formatted copy of<br />
mass storage file to<br />
tape file<br />
@COPY,I elt,tape. Copy symbolic element<br />
to SDF tape file<br />
@COPY,IO elt,tape. Copy omnibus element<br />
to tape file<br />
@COPY,V ms.,tape. Copy variable block size<br />
mass storage file to<br />
tape file<br />
@COPY tape.,ms. Unformatted copy of<br />
tape file to mass<br />
storage file<br />
Not available<br />
Not available<br />
Not available<br />
COPY_RAF_SAF<br />
Not available<br />
Not available<br />
Not available<br />
Copy tape file to mass storage file<br />
Not available<br />
7830 9796–013 B–3
Summary of FURPUR Commands<br />
Table B–1. Summary of FURPUR Commands<br />
FURPUR Command Description PCFP Function Packet Fields<br />
@COPY,B tape.,ms. Copy FORTRAN tape<br />
file to mass storage<br />
data file<br />
@COPY,F tape.,SDF Copy SDF tape file to<br />
mass storage file<br />
@COPY,G tape.,ms. Formatted copy of tape<br />
file to mass storage file<br />
@COPY,I tape.,elt Copy SDF tape file to<br />
symbolic element<br />
@COPY,IO tape.,elt Copy tape file to<br />
omnibus element<br />
@COPY,N tape.,ms. Copy tape file with<br />
abnormal frame count<br />
to mass storage file<br />
@COPY,V tape.,ms. Copy variable block size<br />
tape file to mass<br />
storage file<br />
@COPY<br />
tape.,tape.[,#files]<br />
Not available<br />
Not available<br />
COPY_SAF_RAF<br />
Not available<br />
Not available<br />
Not available<br />
Not available<br />
Copy tape file to tape file<br />
Unformatted copy of<br />
tape files to tape files;<br />
see note 7<br />
@COPY,F SDF.,SDF Copy SDF tape file to<br />
SDF tape file<br />
@COPY,M<br />
tape.,tape.[#files]<br />
Unformatted copy of<br />
tape files to tape files<br />
with hardware EOF<br />
mark separating files;<br />
see note 7<br />
@COPY,N tape.,tape. Copy tape file with<br />
abnormal frame count<br />
to tape file<br />
@COPY,T tape.,tape. Copy 8-bit labeled tape<br />
file to tape file<br />
@CYCLE file. Display F-cycle<br />
information<br />
@CYCLE file.,#cycles Set maximum F-cycle<br />
range<br />
Not available<br />
Not available<br />
Not available<br />
Not available<br />
Not available<br />
ACQ_FILE_INFO INFO_DETAIL=<br />
LONG or<br />
COMPLETE<br />
CHG_FILE_CYC MAX_F_CYCLES=<br />
#cycles<br />
B–4 7830 9796–013
Summary of FURPUR Commands<br />
Table B–1. Summary of FURPUR Commands<br />
FURPUR Command Description PCFP Function Packet Fields<br />
@CYCLE elt,#cycles Set maximum element<br />
cycle range<br />
@DELETE<br />
file1.,[,file2.,...]<br />
@DELETE,AORS<br />
elt1[,elt2,...]<br />
Delete files; see notes 8<br />
and 15<br />
Delete elements; see<br />
notes 1, 2, 3, and 8<br />
@DELETE,UAORS Undelete elements; see<br />
notes 1, 2, 3, and 8<br />
@ENABLE<br />
file1.[,file2.,...]<br />
Clear disable indicators<br />
for files; see note 8<br />
@ERS file1.[,file2.,...] Erase files; see notes 8<br />
and 9<br />
@FIND tape. Locate an element on<br />
an element format tape<br />
@MARK tape. Write hardware EOF<br />
mark on a tape<br />
CHG_ELT NEW_CYCLE_<br />
LIMIT=#cycles<br />
DELETE_FILE<br />
DELETE_ELT<br />
UNDELETE_ELT<br />
CHG_FILE DIRECTORY_<br />
DISABLE=<br />
SET_OFF<br />
WRITE_DISABLE=<br />
SET_OFF<br />
BACKUP_<br />
DISABLE=<br />
SET_OFF<br />
CACHE_<br />
DISABLE=<br />
SET_OFF<br />
ERASE_RAF STORAGE_TO_<br />
RELEASE=ALL_<br />
BUT_INITIAL_<br />
RESERVE<br />
ZERO_FIRST_<br />
TRACK_ONLY_IF_<br />
WRITTEN=TRUE<br />
Not available<br />
Not available<br />
@MOVE tape.[,#files] Move tape forward MOVE_SAF TYPE_OF_MOVE=<br />
FORWARD<br />
MOVE_NUM=<br />
#files<br />
@MOVE,B<br />
tape.[,#files]<br />
Move tape backward MOVE_SAF TYPE_OF_MOVE=<br />
BACKWARD<br />
MOVE_NUM=<br />
#files<br />
POSITION_AT_<br />
END_OF_LOG_<br />
FILE=TRUE<br />
CURRENT_VOL_<br />
ONLY=TRUE<br />
7830 9796–013 B–5
Summary of FURPUR Commands<br />
Table B–1. Summary of FURPUR Commands<br />
FURPUR Command Description PCFP Function Packet Fields<br />
@PACK pf1.[,pf2.,...] Remove deleted<br />
elements; see notes 8,<br />
9, 10, and 11<br />
@PACK,P<br />
pf1.[,pf2.,...]<br />
Remove deleted<br />
elements and create<br />
entry point tables; see<br />
notes 8, 9, 10, and 11<br />
@PCH elt Punch symbolic<br />
element<br />
@PREP pf1.[,pf2.,...] Create entry point<br />
tables; see notes 8 and<br />
12<br />
@PRT Print master file<br />
directory (MFD)<br />
@PRT,D<br />
pack1[,pack2,...]<br />
@PRT,F<br />
file1.[,file2.,...]<br />
Print files on named<br />
removable packs<br />
Print information for<br />
files; see notes 8 and<br />
13<br />
@PRT,IL Print file information<br />
about files assigned to<br />
the run; see note 14<br />
@PRT,N Print files by account<br />
number<br />
PACK_PF<br />
PACK_PF<br />
PREP_PF<br />
Not available<br />
EP_TYPE=BOTH<br />
PREP_PF EP_TYPE=BOTH<br />
Not available<br />
Not available<br />
ACQ_FILE_INFO INFO_DETAIL=<br />
LONG or<br />
COMPLETE<br />
ACQ_FILE_LIST INFO_DETAIL=<br />
LONG or<br />
COMPLETE<br />
SEARCH_SET=<br />
KNOWN_TO_<br />
RUN<br />
Not available<br />
@PRT,P Print files by project-id Not available<br />
@PRT,S elt1[,elt2,...] Print symbolic element<br />
contents<br />
@PRT,T pf1.[,pf2.,...] Print element<br />
information; see notes<br />
1, 2, 3, 8, and 14<br />
@PRT,U<br />
pack1[,pack2,...]<br />
@REWIND<br />
tape1.[,tape2.,...]<br />
Print usage of named<br />
removable packs<br />
Rewind tapes to load<br />
point; see notes 5 and 8<br />
Not available<br />
ACQ_ELT_INFO<br />
ACQ_REL_EP_<br />
INFO<br />
ACQ_OM_EP_<br />
INFO<br />
ACQ_PROC_INFO<br />
Not available<br />
MOVE_SAF TYPE_OF_MOVE=<br />
TO_SAF_START<br />
B–6 7830 9796–013
Notes:<br />
1. Specify FURPUR options in a PCFP function packet as follows:<br />
• Specify the A option by setting ABS_TYPE = TRUE.<br />
• Specify the O option by setting OMN_TYPE = TRUE.<br />
• Specify the R option by setting REL_TYPE = TRUE.<br />
• Specify the S option by setting SYM_TYPE = TRUE.<br />
Summary of FURPUR Commands<br />
Setting all four PCFP function packet conditions to either TRUE or FALSE can specify<br />
all four FURPUR options.<br />
2. The FURPUR Y option is used together with the A option and the third FURPUR<br />
parameter to specify absolute element subtype. The PCFP function packet provides<br />
the ABS_SUBTYPE condition array to provide this capability.<br />
• Specify the FURPUR third parameter value of ABS in a PCFP function packet by<br />
setting ABS_SUBTYPE(0) = TRUE.<br />
• Specify OM by setting ABS_SUBTYPE(1) = TRUE.<br />
• Specify SD by setting ABS_SUBTYPE(2) = TRUE.<br />
• Specify ZM by setting ABS_SUBTYPE(3) = TRUE.<br />
• Specify BOM by setting ABS_SUBTYPE(17) = TRUE.<br />
3. The format of the element name, the presence of the FURPUR V option and the *<br />
version name masking character together are used to select program file elements<br />
from a source file. Analogous element selection capabilities are provided in a PCFP<br />
function packet using different formats of the ELT_NAME and ELT_VERSION fields<br />
and the ? PCFP wild-card character. Note that the PCFP function packet must have<br />
QUESTION_MARK_MATCHES_SPACE = TRUE for the ? wild-card character to<br />
operate the same as the FURPUR * version name mask character.<br />
4. The FURPUR X option is used together with the format of the element name to<br />
determine the element name and version name to be used for a destination file.<br />
Analogous element naming capabilities are provided in a PCFP function packet using<br />
different formats of the NEW_ELT_NAME (or DEST_ELT_NAME) and<br />
NEW_ELT_VERSION (or DEST_ELT_VERSION) fields.<br />
5. Specify the FURPUR I option in the PCFP MOVE_SAF function packet by setting<br />
INTERLOCK = TRUE.<br />
6. Specify the FURPUR L option in the PCFP COPY_ELT function packet by setting<br />
COPY_CURRENT_CYCLE = TRUE.<br />
7. The only tape to tape copy supported by PCFP is the COPY_SAF_SAF function,<br />
which can be used to copy a single file created by the FURPUR @COPY,G ms.,tape.<br />
command or by the PCFP COPY_RAF_SAF function to a destination tape file.<br />
8. The FURPUR command can process up to 63 files on one command line; the PCFP<br />
function can process only one file on each PCFP function call.<br />
7830 9796–013 B–7
Summary of FURPUR Commands<br />
9. Specify FURPUR options in a PCFP function packet as follows:<br />
• Specify the FURPUR I option by setting STORAGE_TO_RELEASE =<br />
ALL_STORAGE.<br />
• Specify the FURPUR N option by setting STORAGE_TO_RELEASE = NONE.<br />
• Specify the FURPUR Z option by setting ZERO_RELEASED_STORAGE = TRUE.<br />
• Specify the FURPUR G option (@ERS only) by setting<br />
ZERO_RETAINED_STORAGE = TRUE.<br />
10. The FURPUR D, L and M options are not available on the PCFP PACK_PF function.<br />
11. The FURPUR A, O, R, S and Y options are not directly available on the PCFP<br />
PACK_PF function. The affect of these options can be achieved using PCFP by<br />
performing a DELETE_ELT function with the proper settings for ABS_TYPE,<br />
OMN_TYPE, REL_TYPE, SYM_TYPE, and the ABS_SUBTYPE array, followed by a<br />
PACK_PF function.<br />
12. The FURPUR F option can be specified in the PCFP PREP_PF function packet by<br />
setting OVERWRITE_OLD_EP_TABLE = TRUE. The FURPUR L option is not<br />
available on the PCFP PREP_PF function.<br />
13. File caching information displayed by the FURPUR @PRT function is not available<br />
with the PCFP ACQ_FILE_INFO and ACQ_FILE_LIST functions.<br />
14. The FURPUR B option is not available in PCFP.<br />
15. The FURPUR N option is not available in PCFP.<br />
B–8 7830 9796–013
Appendix C<br />
PACK_PF Operation and Performance<br />
Many factors affect the performance of the PACK_PF function. The size of the file to be<br />
packed is the primary factor. Small files can be quickly packed with very little attention<br />
to pack method or to optimizing work area requirements. Large files take a long time to<br />
pack, but careful selection of the pack method and options and attention to work area<br />
requirements can yield big performance improvements. The two pack methods are<br />
described in C.1 and C.2 and their performance is compared in C.3.<br />
C.1. Standard Method Performance<br />
The standard method uses a two-step process to pack a file (see 8.4). The first step<br />
involves rebuilding and rewriting all of the program file tables. For a standard program<br />
file, this is a maximum of 21 tracks for all tables. In almost every case, this is much<br />
smaller than the element text to be copied in the second step. Even for a large program<br />
file, where the element table is a maximum of 146 tracks for 26,146 elements or where<br />
all maximum size tables total 584 tracks, the program file tables are usually much smaller<br />
than the element text. This means that the performance of the first step is almost<br />
always a very small component of the total performance of the PACK_PF function,<br />
particularly as the number of undeleted elements and the size of the element text<br />
increases.<br />
During the second step of the standard method, the text of remaining elements is<br />
copied, if necessary, so that the text of each element immediately follows the text of the<br />
previous element. If the element text is copied, the corresponding element table entry is<br />
updated and all associated procedure table entries are updated. In this step,<br />
performance is affected by<br />
• The amount of element text to copy.<br />
• The amount of work area provided for the I/O buffer (W in the standard method work<br />
area formula described in 8.4.4.1).<br />
• The number of elements with element text to copy.<br />
• The specification for the REDUCE_IO condition item in the function packet.<br />
7830 9796–013 C–1
PACK_PF Operation and Performance<br />
Consider two nearly identical files, each with 100 elements. In the first file, the first<br />
element is deleted and in the second file, the last (100th) element is deleted.<br />
• For the first file, the text of all 99 undeleted elements is copied to close up the file<br />
and remove the element text associated with the first element. For this file, all<br />
element entries and associated procedure table entries must also be updated.<br />
• For the second file, none of the text of the 99 undeleted elements is copied since<br />
the deleted text follows the text of the first 99 elements. For this file, no updates to<br />
element entries or procedure table entries are required.<br />
The performance for the first file where updates are required to all element entries, all<br />
procedure table entries, and all element text is much slower than for the second file<br />
where no updates are required.<br />
Another consideration is the presence of Object Module Entry Point Tables, which are<br />
removed by the PACK_PF function and are located in the element text area of the file.<br />
Even if there are no deleted elements in a file, there may by one or more Object Module<br />
Entry Point Tables to be removed. For example, if when the second file described earlier<br />
was created, a PCFP PREP_PF function or a FURPUR @PACK,P or @PREP command<br />
was performed immediately after the first element was written to the file, an Object<br />
Module Entry Point Table is written between the text for elements 1 and 2. When the<br />
file is packed, the element text for elements 2 – 99 is copied to close up the file and<br />
remove the Object Module Entry Point Table. The element entry and procedure table<br />
entries for each of these elements also require updates.<br />
The ACQ_BASIC_PF_INFO function with GET_SUMMARY_INFO = TRUE can be used to<br />
return the values DEAD_SPACE, PACK_PF_NUM_ELTS_TO_UPDATE, and<br />
PACK_PF_TEXT_SIZE_TO_COPY. Both deleted elements and Object Module Entry Point<br />
Tables are considered when these values are calculated. The last two values indicate<br />
the exact number of elements that require updates and the amount of element text that<br />
would have to be copied by PACK_PF to close up the file.<br />
When the amount of element text to copy is large, it is very important that sufficient<br />
work area be provided for the I/O buffer used during the text copy. To maximize<br />
function performance, follow the recommendations for W in 8.4.4.1.<br />
During the second step, each time element text is copied, text pointers in the element<br />
entry and in the associated procedure table entries must be updated to correctly identify<br />
the new location of the element text. The default action is to immediately write the<br />
updated entries to mass storage. The smallest write performed is one 28-word sector.<br />
Therefore, writing each 10 word element entry results in 28 words being written, or 56<br />
words being written when the element entry spans two sectors. This means that each<br />
sector is written multiple times as element entries are updated. For the element table,<br />
each sector is written an average of 3.6 times. For 4-word procedure table entries, each<br />
28-word sector is written an average of seven times. This combination of writing<br />
sectors multiple times and numerous small writes is extremely inefficient, and results in<br />
a very significant decrease in performance for the default action.<br />
C–2 7830 9796–013
PACK_PF Operation and Performance<br />
This is the reason for the REDUCE_IO function packet condition item. When this item is<br />
set to TRUE, updated element table entries and procedure table entries are not<br />
immediately written to mass storage. Instead, the writes are delayed until after the<br />
element text for all elements has been copied. Then, the entire element table and each<br />
of the updated procedure tables are written with a single I/O request. Replacing multiple<br />
writes of small buffers with single writes of large buffers reduce the total amount of I/O<br />
and the total number of I/O requests. This increases the efficiency of the I/O and the<br />
overall performance of the function. Note that specification of REDUCE_IO does affect<br />
the contents of the file in case of system or function failure as described in C.4.<br />
The size of the element text to be copied during a standard method pack is usually much<br />
larger than the size of the program file element table and procedure tables. For this<br />
reason, a greater performance benefit is usually realized by providing the recommended<br />
I/O buffer in the work area formula rather than by specifying REDUCE_IO in the function<br />
packet. To illustrate this, the standard method is used to pack a file with 200 elements,<br />
the first of which is deleted, with no procedure tables and with each element having one<br />
track (1,792 words) of element text. Table C–1 shows the performance results while<br />
using the minimum I/O buffer size of 112 and the recommended I/O buffer size of 1,792<br />
and with REDUCE_IO equal to both FALSE and TRUE. Table C–1 lists the average<br />
elapsed time (wall clock time) for the PACK_PF function and the total Standard Unit of<br />
Processing (SUP) time in seconds. The results were obtained on a nearly idle 2200/524<br />
system and were averaged over a minimum of 10 function repetitions. Results on<br />
different 2200 IX models may vary.<br />
Table C–1. Standard Method Performance Comparison<br />
I/O Buffer Size REDUCE_IO=FALSE REDUCE_IO=TRUE<br />
112 76 seconds<br />
212 SUP seconds<br />
1792 9 seconds<br />
Notes:<br />
23 SUP seconds<br />
73 seconds<br />
206 SUP seconds<br />
5 seconds<br />
17 SUP seconds<br />
• In all four cases, the average elapsed time and the SUP seconds during the first step<br />
of the standard method were identical and were less than 0.2 seconds. The<br />
remainder of the time was spent during the second step of the standard method.<br />
• When the I/O buffer is increased from 112 to 1,792 words and REDUCE_IO is<br />
FALSE, PACK_PF takes an average of only 12 percent of the elapsed time and 11<br />
percent of the SUPs.<br />
• Setting REDUCE_IO to TRUE with the 112-word I/O buffer does not result in much<br />
of a performance improvement.<br />
• The best results are achieved with the recommended I/O buffer of 1,792 words and<br />
REDUCE_IO is TRUE (1,792/TRUE). Compared to 112/FALSE, 1,792/TRUE takes an<br />
average of only 7 percent of the elapsed time and 8 percent of the SUPs. Compared<br />
to 1,792/FALSE, 1,792/TRUE takes an average of 56 percent of the elapsed time and<br />
74 percent of the SUPs.<br />
7830 9796–013 C–3
PACK_PF Operation and Performance<br />
• 1,792 words is used for the recommended I/O buffer size because this is the size of<br />
the largest element to be copied in the file. See 8.4.4.1 for the complete description<br />
of the I/O buffer size recommendation.<br />
C.2. Copy Method Performance<br />
The copy method uses a two-step process to pack a file, as described in 8.4. The first<br />
step uses the COPY_ELT function to copy undeleted elements, associated procedure<br />
table entries, and associated element text to a temporary file. The second step uses the<br />
COPY_RAF_RAF function to copy the temporary file back to the program file. In the<br />
standard method, the number of elements copied and the performance of the function<br />
can be affected by the location of deleted elements in the file and by the presence of<br />
Object Module Entry Point Tables in the file. The copy method always copies all<br />
undeleted elements, procedure table entries, and element text twice, once during each<br />
step. The performance of the function depends mainly on the amount of element text to<br />
copy and the work area provided. The number of elements and text size to copy can be<br />
derived from values returned by the ACQ_BASIC_PF_INFO function with<br />
GET_SUMMARY_INFO = TRUE. The number of elements to copy is<br />
ELT_NUM_ENTRIES - NUM_DELETED_ELTS. The text size to copy in words is<br />
TEXT_SIZE - DEAD_SPACE.<br />
In the first step work area formula (see 8.4.4.2), it is crucial for maximum performance to<br />
provide the recommended values for D (temporary file element table buffer) and I (I/O<br />
buffer). The value of I in this formula is nearly identical, except for the minimum allowed,<br />
to the value of W in the standard method formula (see 8.4.4.1). The value for C controls<br />
the efficiency of procedure table copy operations. For maximum efficiency, provide<br />
three words for each undeleted procedure element. If the file contains over 50<br />
undeleted procedure elements, a minimum of 153 words must be provided for C. The<br />
recommended value for S is the initial size of the program file element table buffer. This<br />
value has the least affect on function performance. If possible, the recommended value<br />
should be provided. If necessary, the value for S can be reduced to its minimum value of<br />
252 without seriously impacting function performance.<br />
Unlike the standard method, where the vast majority of work is performed by the second<br />
step, the work performed by the copy method is more evenly divided between the first<br />
and second steps. When the recommended work area is provided for both steps, the<br />
elapsed time and SUP seconds are larger for the first step than for the second step. This<br />
is because the first step copies each element, its procedures, and its text separately<br />
while the second step uses multiple activities to copy tracks in groups without regard to<br />
the file structure. The percentage of time taken by each step is largely dependent on the<br />
average element text size per element. For files averaging one track of element text per<br />
element, the first step takes approximately 90 percent of the elapsed time and 80<br />
percent of the SUP seconds. As the average element text size per element decreases<br />
to the minimum size of 28 words per element, the first step percentages rise to 99<br />
percent of the elapsed time and 95 percent of the SUP seconds. As the average<br />
element text size per element increases to four tracks, the first step percentages fall to<br />
75 percent of the elapsed time and 60 percent of the SUP seconds.<br />
C–4 7830 9796–013
PACK_PF Operation and Performance<br />
Table C–1 shows the standard method performance with different I/O buffer sizes and<br />
settings for the function packet REDUCE_IO item. Using the same file (200 elements<br />
with the first element deleted, no procedure tables, and each element having one track<br />
of element text), Table C–2 shows the copy method performance with the minimum<br />
work area size (4,570 words), the work area size recommended for the first step (6,504<br />
words), the second step (30,470 words), and the maximum work area size for the<br />
second step (60,070 words). The Function Performance column shows the total<br />
performance of the function. The next two columns divide the performance between<br />
the two copy method steps. Like Table C–1, this table lists both the average elapsed<br />
time and the total SUP seconds used. The results were obtained on a nearly idle<br />
2200/524 system and were averaged over a minimum of 10 function repetitions.<br />
Results on different 2200 IX models may vary.<br />
Work Area Size<br />
Table C–2. Copy Method Performance Comparison<br />
4,570 9 seconds<br />
Function<br />
Performance<br />
38 SUP seconds<br />
6,504 8 seconds<br />
37 SUP seconds<br />
30,470 6 seconds<br />
25 SUP seconds<br />
60,070 6 seconds<br />
Notes:<br />
24 SUP seconds<br />
First Step<br />
Performance<br />
5 seconds<br />
18 SUP seconds<br />
5 seconds<br />
18 SUP seconds<br />
5 seconds<br />
18 SUP seconds<br />
5 seconds<br />
18 SUP seconds<br />
Second Step<br />
Performance<br />
3 seconds<br />
20 SUP seconds<br />
3 seconds<br />
20 SUP seconds<br />
1 second<br />
7 SUP seconds<br />
1 second<br />
6 SUP seconds<br />
• Since the table values are rounded to the nearest second, the total values do not<br />
always equal the sum of the first and second steps.<br />
• For both 4,570 and 6,504, the I/O buffer size for both the first and second steps is<br />
1,792 words.<br />
• The first step performance improves only fractionally for work area sizes greater than<br />
the recommended value of 6,504 words.<br />
• For all work area sizes, the elapsed times are at least as good as those listed in Table<br />
C-1 (standard method) with a 1,792 word I/O buffer and REDUCE_IO = FALSE<br />
(1,792/FALSE).<br />
• For 30,470 and 60,070, the SUP seconds are similar to Table C-1 (standard method)<br />
1,792/FALSE and the elapsed times are similar to 1,792/TRUE.<br />
7830 9796–013 C–5
PACK_PF Operation and Performance<br />
C.3. Performance Comparison<br />
Tables C–1 and C–2 compare the PACK_PF performance of the standard method to the<br />
copy method for one small, 200-element file. This is only one performance example.<br />
This subsection generally compares the performance of the standard method to the copy<br />
method. These comparisons assume that the work area provided conforms to the<br />
recommendations described in 8.4.4.<br />
The following items relate to the PACK_PF performance comparisons:<br />
• Elapsed time or wall clock time is the most variable performance measurement,<br />
varying widely depending on the time of day, system activity, subsystem activity,<br />
and so forth. Identical PACK_PF functions on identical files may have widely varied<br />
elapsed times, even when performed consecutively.<br />
• SUP seconds retrieved by ER INFO$ are the most consistent performance<br />
measurement, although the results do not always correlate directly to the observed<br />
performance.<br />
• In almost all cases, assuming the same number of elements to update and the same<br />
amount of text to copy, the standard method with REDUCE_IO = TRUE is the<br />
fastest followed by the copy method. The standard method with REDUCE_IO =<br />
FALSE is the slowest .<br />
• For a medium size file of 1,000 elements, each with one track (1,792 words) of text,<br />
the following are the approximate performance ratios of the standard method with<br />
REDUCE_IO = TRUE : copy method : standard method with REDUCE_IO = FALSE.<br />
− For elapsed time, the ratio is 1 : 1.10 : 2.50<br />
− For SUP seconds, the ratio is 1 : 1.25 : 1.40<br />
• As the number of elements increases to large files of 10,000 elements and more,<br />
the performance ratios for both elapsed time and SUP seconds remain nearly<br />
unchanged.<br />
• As the number of elements decreases to small files of 100 elements, the relative<br />
performance of the copy method becomes slower and the relative performance of<br />
the standard method with REDUCE_IO = FALSE becomes faster, as follows:<br />
− For elapsed time, the ratio is 1 : 1.60 : 2.20<br />
− For SUP seconds, the ratio is 1 : 1.65 : 1.40<br />
• As the average text size per element increases, the relative performance of the copy<br />
method is nearly unchanged in terms of elapsed time, but becomes much slower in<br />
terms of SUP seconds. The standard method with REDUCE_IO = FALSE becomes<br />
faster, both in terms of elapsed time and SUP seconds.<br />
• The ACQ_BASIC_PF_INFO return item PACK_PF_NUM_ELTS_TO_UPDATE is the<br />
number of elements that will be updated by the standard method and the difference<br />
between ACQ_BASIC_PF_INFO return items ELT_NUM_ENTRIES and<br />
NUM_DELETED_ELTS is the number of undeleted elements that will be copied by<br />
the copy method. As the ratio of the first item to the second decreases, the<br />
performance of the standard method for both REDUCE_IO values improves against<br />
the copy method.<br />
C–6 7830 9796–013
C.4. File Contents in Error Cases<br />
PACK_PF Operation and Performance<br />
As with any PCFP function that modifies a file, a system failure or function error during a<br />
PACK_PF may leave the file in an indeterminate state. To avoid the possibility of lost or<br />
inaccessible data, insure that there is a current back-up copy of the file available before<br />
performing a PACK_PF function. In most cases, following a system or function failure it<br />
is not possible to determine the state of the file. None of the PCFP program file<br />
information functions described in Section 6 or the FURPUR @PRT,TL command can be<br />
used to verify the validity of the file contents. For most error scenarios, it may appear<br />
from the Table of Contents that the PACK_PF function has completed, when actually not<br />
all of the program file tables have been updated and not all of the element text has been<br />
copied. In all cases of system failure or function failure, it is recommended that the file<br />
be reloaded from its backup copy.<br />
The following paragraphs describe the pack methods with particular regard to the<br />
contents of the file in various error scenarios.<br />
The first step of the standard method removes all deleted elements and procedure table<br />
entries and rewrites the tables in the following order:<br />
1. Element Table<br />
2. Assembler Procedure Table<br />
3. COBOL Procedure Table<br />
4. FORTRAN/PLUS Procedure Table<br />
5. File Table Index (FTI)<br />
Since the FTI, which contains the size of individual tables is the last table written, a<br />
failure during this step is likely to leave the program file with inconsistent or invalid tables<br />
consisting of entries from both before and after the pack. Since the first step is usually a<br />
very small percentage of the total elapsed time for the function, this scenario is much<br />
less likely than a failure during the second step.<br />
When the first step has been successfully completed, the deleted entries have been<br />
removed from the program file tables but no text has been copied. During the second<br />
step, the contents of the file in case of a failure depend on the selected value of<br />
REDUCE_IO.<br />
When REDUCE_IO is FALSE (default), each element entry and its associated procedure<br />
table entries are rewritten to their tables immediately after copying the element text for<br />
the entry. This means that only the element being processed at the time of a failure is<br />
affected. Typically, a failure results in the element text being partially overwritten or in<br />
procedure table entries referencing incorrect mass storage addresses. However, it is<br />
difficult to determine which element has been affected by the failure.<br />
7830 9796–013 C–7
PACK_PF Operation and Performance<br />
When REDUCE_IO is TRUE, the element entries and procedure table entries are not<br />
rewritten to their tables until after all of the element text for the file is copied. This<br />
means that all of the element entries and procedure table entries for which element text<br />
has been copied are affected in case of a failure. Typically, a failure results in the<br />
element text of each affected element being overwritten and in each affected procedure<br />
table entry referencing an incorrect mass storage address. Even though the number of<br />
elements affected in case of a failure is much greater, the improved performance offered<br />
with REDUCE_IO = TRUE means that the elapsed time that the file is vulnerable to a<br />
failure is much smaller.<br />
The copy method offers the best combination of performance and file safety. This is<br />
because the file is not modified in any way during the first step, which takes a majority<br />
of the elapsed time for the function. The file is not modified until the second step, when<br />
the temporary file created during the first step is copied back to the original file. The file<br />
is copied sequentially from the first track to the end of the element text. This means<br />
that these items are written in the following order followed by the tracks of element<br />
text:<br />
1. FTI<br />
2. Element Table<br />
3. Assembler Procedure Table<br />
4. COBOL Procedure Table<br />
5. FORTRAN/PLUS Procedure Table<br />
If the program file tables are only partially written when a failure occurs, it is likely to<br />
leave the program file with inconsistent or invalid tables consisting of entries from both<br />
before and after the pack. This is similar to a failure during the first step of the standard<br />
method. Since the program file tables are usually much smaller than the element text,<br />
the more likely error scenario is that the element text was only partially written at the<br />
time of the failure. In this case, elements would have invalid text.<br />
C–8 7830 9796–013
Glossary<br />
A<br />
absolute cycle<br />
See F-cycle, element cycle.<br />
absolute element<br />
A type of element that is ready for execution on an 1100/2200 processor or one that<br />
contains a special definition called a subsystem definition. There are five subtypes of<br />
absolute elements: absolute (ABS), object module (OM), bound object module (BOM),<br />
zero overhead object module (ZOOM), and subsystem definition (SSD).<br />
access control record (ACR)<br />
A record containing a list of users, the accesses they may have to a file, and the<br />
conditions under which they are allowed access. Attaching an ACR to a file makes the<br />
file semiprivate.<br />
account-id<br />
An identifier specifying an account charged with processing time and system resources<br />
consumed during a run. Also called account number. You can use account identifiers to<br />
control access to objects by specifying them in ACRs.<br />
arithmetic fault modes<br />
The two modes that indicate how an 1100/2200 processor should handle certain<br />
floating-point errors. The two modes are noninterrupt and compatible.<br />
array<br />
B<br />
A series of data items or data structures, all of the same form.<br />
Basic Services Package (BSP)<br />
A set of program-callable routines in the system library for handling and updating the<br />
table of contents (TOC) in a program file.<br />
block numbering<br />
A hardware block number appended to each data block written to tape. This block<br />
number helps with error recovery of data by allowing the detection of tape movement.<br />
Block numbering also helps to ensure data integrity by making it easier to detect extra or<br />
missing data blocks.<br />
block size<br />
The size of a physical data block written to tape. Under the FURPUR tape format, the<br />
block size is always a multiple of a track (1,792 words).<br />
7830 9796–013 Glossary–1
Glossary<br />
C<br />
calling program<br />
In the context of this reference manual, a calling program is a program written in C,<br />
COBOL, or FORTRAN, which calls one or more functions of PCFP.<br />
cataloged file<br />
A file known to and retained by the Executive, for an indefinite period not necessarily<br />
related to the life of a particular run, and generally usable by runs other than the run<br />
which originally created the file. See also lifetime, temporary file.<br />
character item<br />
A data item that contains ASCII character strings in structures used to interface with<br />
PCFP. For each character item, the maximum length of the string is given in the item<br />
description.<br />
checksum<br />
A software data integrity scheme that can be used for data written to tape. A checksum<br />
is computed by taking the arithmetic sum of every word in a track of data, and writing<br />
this value to tape along with the track. When the data is read from tape, the checksum<br />
is computed once again. A checksum error occurs if the checksum computed when the<br />
data is read does not match the checksum that was computed when the data was<br />
written.<br />
clearance level<br />
A hierarchical classification for files for security purposes. Clearance levels can range<br />
from 0 to 63, with 63 being the most restrictive. Clearance levels can also be associated<br />
with symbolic labels such as unclassified, classified, secret, and top secret.<br />
condition item<br />
A data item that can assume only the values TRUE and FALSE. Internally, TRUE is<br />
represented by 1, and FALSE is represented by 0.<br />
conformance to standard calling sequence<br />
See standard calling sequence.<br />
copy procedure<br />
A part of a symbolic element that you dynamically include as part of a COBOL program<br />
using the COPY statement. The copy procedures supplied with PCFP have been<br />
processed by the PDP processor, and reside in program file SYS$LIB$*PROC$, which is<br />
searched automatically by the COBOL compiler. See also include element, include<br />
procedure.<br />
COPY,G format<br />
See FURPUR format.<br />
cycle<br />
See F-cycle, element cycle.<br />
Glossary–2 7830 9796–013
D<br />
Glossary<br />
data compression<br />
A hardware feature on certain tape subsystems that reduces the amount of physical tape<br />
required to record data by removing repetitive information before recording it. This<br />
feature compresses data that is written to tape by a ratio of 3:1 or better. In order to use<br />
data compression, you must also use block numbering.<br />
data item<br />
A data entity that contains a single value. Sometimes referred to simply as item.<br />
data structure<br />
A data entity composed of several data items that are considered as a unit. Sometimes<br />
called a packet. PCFP parameters are data structures.<br />
date-time item<br />
A data item that can assume date and time values. All date-time items are two words<br />
long, and contain the subitems year, month, day, and milliseconds.<br />
default value<br />
In the context of this <strong>Reference</strong> <strong>Manual</strong>, the default value of an item is the value whose<br />
internal representation is zero. Thus, when a calling program zero-fills a data structure, it<br />
sets all items in that structure to their default values. At that point, the calling program<br />
needs to assign values explicitly only to those items that require a nondefault value. For<br />
character items, the default value is null.<br />
deleted element<br />
An element in a program file that is marked for removal from the file.<br />
density<br />
The amount of data stored per unit length or area of a storage medium, such as tape.<br />
Tape density is measured in bits per inch.<br />
destination file<br />
The file into which data is written during a copy operation.<br />
directory-id<br />
An identifier used to distinguish between the master file directories in a file-sharing<br />
environment. Each directory has a directory-id for use in file creation and assignment.<br />
Shared files use the SHARED directory-id and local files use the STD (standard)<br />
directory-id.<br />
E<br />
element<br />
A named unit of data within a program file. The nature of the data within an element<br />
depends on the type the element, which is one of the following: absolute, omnibus,<br />
relocatable, or symbolic. Within a program file, each undeleted element is uniquely<br />
identified by the combination of its name, version, and type.<br />
7830 9796–013 Glossary–3
Glossary<br />
element cycle<br />
One of the stages a symbolic element goes through as it is updated. Also called a<br />
symbolic element cycle. A specific element cycle is identified by one of two numbers:<br />
an absolute element cycle number or a relative element cycle number. An absolute<br />
element cycle number must be between 0 and 62 inclusive, and does not change as<br />
new element cycles are created. A relative element cycle number must be between -62<br />
and 0 inclusive, and indicates a particular element cycle relative to the current cycle.<br />
Relative element cycle numbers change as new element cycles are created.<br />
element subtype<br />
A further classification of elements beyond the type classification. The subtype of an<br />
element typically indicates the system processor that produced or can process the<br />
element.<br />
element table<br />
A table within a program file's table of contents. Each entry within this table identifies<br />
and describes a unique element in the program file.<br />
element type<br />
One of the basic classifications of elements, based upon the nature of the data in the<br />
element. The four element types are absolute, omnibus, relocatable, and symbolic.<br />
ELMS<br />
See Extended Language Message System.<br />
entry point<br />
A location within a relocatable element or an object module that can be referenced by<br />
other relocatable elements or object modules respectively. There are two types of entry<br />
points: those occurring in relocatable elements (relocatable entry points), and those<br />
occurring in object modules (object module entry points).<br />
entry point table<br />
A table within a program file's table of contents containing entries that describe all of the<br />
entry points of a specific type in the program file. There are two entry point tables, one<br />
that describes relocatable entry points and one that describes object module entry<br />
points.<br />
EOF mark<br />
A hardware code that indicates there is no more data in a logical file on tape. On<br />
magnetic tape, an EOF mark is written after each logical file, and two EOF marks are<br />
written to indicate the logical end of the tape file. Also called end-of-file mark.<br />
error<br />
A situation that was detected during execution of a PCFP function that prevented<br />
completion of the function. The nature of the error is returned as an error code to the<br />
calling program.<br />
Glossary–4 7830 9796–013
Glossary<br />
error code<br />
The value returned by each PCFP function to calling programs written in C and<br />
FORTRAN. Also, an item in the generic part of the function packet that contains the<br />
same value. The error code indicates the warning condition or error (if any) that occurred<br />
during processing of a PCFP function. The form of the error codes returned by PCFP is<br />
an ELMS condition-id, which can be supplied as a parameter to ELMS to produce an<br />
explanatory message.<br />
exclusive assign<br />
The assignment of a file such that the run making the assignment is the only run that can<br />
access the file (@ASG,AX). Access by other runs is denied until the exclusive<br />
assignment is released.<br />
Extended Language Message System (ELMS)<br />
A message processing system used by software applications in the OS 2200<br />
environment. When an application uses ELMS for message processing, the messages<br />
are defined, maintained, and processed separately from the application. This gives the<br />
application independence from its messages and the run-time environment.<br />
F<br />
F-cycle<br />
One of the stages a file goes through as it is updated. Also called a file cycle. A specific<br />
F-cycle is identified by one of two numbers: an absolute F-cycle number or a relative<br />
F-cycle number. An absolute F-cycle number must be between 1 and 999 inclusive, and<br />
does not change as new F-cycles are created. A relative F-cycle number must be<br />
between -31 and +1 inclusive, and indicates a particular F-cycle relative to the current<br />
cycle. Relative F-cycle numbers change as new F-cycles are created.<br />
F-cycle series<br />
A collection of files with the same directory-id, qualifier, and file name but with different<br />
F-cycle (file cycle) numbers. Up to 32 files can exist in a single F-cycle series.<br />
file<br />
An area of storage used to contain programs or data. A file can be random access (RAF)<br />
or sequential access (SAF). The lifetime of a file can be temporary or cataloged.<br />
file identifier<br />
A parameter of many PCFP functions that uniquely identifies the file or one of the files<br />
on which the function is to operate. The file identifier data structure contains items that<br />
specify the directory-id, qualifier, file name, F-cycle, read key, and write key of the file on<br />
which the function is to operate.<br />
file owner<br />
The user that controls access to a file by other users. Initially, the owner of a file is the<br />
user that created the file.<br />
file sharing<br />
See Multi-Host File Sharing (MHFS).<br />
7830 9796–013 Glossary–5
Glossary<br />
function<br />
A subroutine that performs a specific operation and returns a value to the calling<br />
program. A program invokes PCFP by calling one of the functions defined for PCFP.<br />
function packet<br />
The first parameter of all PCFP functions. It acts both as an input parameter and as an<br />
output parameter. It is the data structure through which the calling program specifies all<br />
options that apply to the function, and through which PCFP passes certain fixed-size<br />
return information back to the calling program. Function packets consist of a generic<br />
part, a return-information part (some functions only), and a specific part.<br />
FURPUR<br />
A set of file utility routines that are part of the OS 2200 Operating System. In<br />
conjunction with the Executive, FURPUR provides the user with a simplified method of<br />
controlling and moving data within OS 2200 files and elements.<br />
FURPUR format<br />
A tape format used to encode a logical file on a sequential-access file. Sometimes called<br />
COPY,G format. The first block of the logical file is a 28-word logical file descriptor,<br />
which contains the following information about the logical file: file name, qualifier,<br />
F-cycle, highest track written, date and time of copy, equipment code, block size.<br />
Subsequent blocks of the logical file contain 1 to 16 tracks of data, with each track<br />
preceded by a two-word track header containing the track sequence number, the<br />
checksum for the track (optional), the mass storage address of the track, and the<br />
indicator for last track of the logical file. There are two minor variations of the FURPUR<br />
tape format: the revised variant, which is the default written by PCFP, and the obsolete<br />
variant, which is written by the FURPUR @COPY,G command and can be written by<br />
PCFP. The revised variant offers performance improvements over the obsolete variant,<br />
and should be used whenever possible. Both PCFP and FURPUR can read both variants<br />
of the FURPUR tape format.<br />
G<br />
generic part of function packet<br />
The part of the function packet for each PCFP function that is the same for every PCFP<br />
function. The generic part of each function packet is contained in the first ten words of<br />
the function packet.<br />
granule<br />
I<br />
The increment by which storage space is allocated to a mass storage file. A granule can<br />
be either a track (1,792 words) or a position (64 tracks).<br />
include element<br />
A symbolic element that you dynamically include as part of a C program using the<br />
#include statement. The include elements supplied with PCFP reside in program file<br />
SYS$LIB$*PROC$, which is searched automatically by the C compiler. See also copy<br />
procedure, include procedure.<br />
Glossary–6 7830 9796–013
Glossary<br />
include procedure<br />
A part of a symbolic element that you dynamically include as part of a FORTRAN<br />
program using the INCLUDE statement. The include procedures supplied with PCFP<br />
have been processed by the PDP processor, and reside in program file<br />
SYS$LIB$*PROC$, which is searched automatically by the FORTRAN compiler. See also<br />
copy procedure, include element.<br />
initial reserve<br />
The mass storage space that is allocated to a mass storage file upon its inception.<br />
integer item<br />
A data item that can assume numeric values in structures used to interface with PCFP.<br />
Each integer item can either be signed, which implies that it can contain either zero, a<br />
positive number, or a negative number, or it can be unsigned, which implies that it can<br />
contain only zero or a positive number.<br />
internal name<br />
An alternate name for a file, given to the file with an @USE control statement. The<br />
original name of the file (the name given to the file when it was created) is called an<br />
external file name. Internal file names, also called use names, are used to simplify file<br />
references (when the external file name is long), to differentiate between files that have<br />
the same basic file name but different qualifiers or F-cycles, and to associate internally<br />
programmed names with specific files.<br />
item<br />
L<br />
labeling<br />
See data item.<br />
See tape labeling.<br />
large element program file<br />
A program file format that is capable of containing elements that have over 262,143<br />
sectors of element text. A large element program file can be initialized with the small,<br />
variable length table structure of a standard program file or with the large, fixed length<br />
table structure of a large program file. See also large program file, program file, and<br />
standard program file.<br />
large program file<br />
A program file format that has large, fixed length tables. The element table can contain<br />
up to 26,146 elements. Each element can contain up to 262,143 sectors of element<br />
text. See also large element program file, program file, and standard program file.<br />
LEPF<br />
lifetime<br />
See large element program file.<br />
The property of a file that indicates its longevity. The two types of file longevity are<br />
temporary and cataloged.<br />
7830 9796–013 Glossary–7
Glossary<br />
logical end<br />
The position on a tape file immediately following the last logical file on the tape.<br />
Sometimes called end of recorded area. When a tape file is positioned at its logical end,<br />
a logical file cannot be copied from the tape file, but a logical file can be written to the<br />
tape file without destroying any data already on the tape file. On an unlabeled tape file,<br />
the logical end is indicated by two consecutive EOF marks; on a labeled tape file, it is<br />
indicated by a special software EOF label.<br />
logical file<br />
The data contained on a sequential-access file that corresponds with a single<br />
random-access file. On an unlabeled tape file, a logical file is delimited by EOF marks; on<br />
a labeled tape file, a logical file is delimited by EOF marks along with special header and<br />
trailer labels. A logical file can span volumes of a tape file.<br />
logical file descriptor<br />
The initial block of data in a logical file on tape. It describes the characteristics of the<br />
logical file but does not contain any data of the logical file.<br />
logical file position<br />
An integer denoting the position of a logical file on a volume of a sequential-access file.<br />
The first logical file on a volume has the logical file position of 1, and the logical file<br />
position of each subsequent logical file is 1 greater than the previous. PCFP considers a<br />
tape to be positioned at a particular logical file if the physical position of the tape is<br />
anywhere between the EOF marks that delimit the logical file.<br />
LPF<br />
M<br />
See large program file.<br />
mass storage<br />
The auxiliary storage that has random-access capability as opposed to, for example,<br />
magnetic tape. Includes all types of disks and solid-state storage.<br />
master file directory (MFD)<br />
The directory maintained by the Executive to control cataloged files. Files listed in the<br />
MFD are retained even after a run terminates.<br />
Multi-Host File Sharing (MHFS)<br />
A feature of the Executive that allows independent closely or loosely coupled system<br />
hosts to access a set of shared mass storage devices. MHFS associates each Executive<br />
file with either a local file directory or a shared file directory, and handles the interhost<br />
communications necessary to deal with file sharing across multiple hosts.<br />
N<br />
null<br />
The value of a character string whose first character is the null character. Since any<br />
character after a null character is disregarded, the value of the entire character string is<br />
considered to be null. Also called null value.<br />
Glossary–8 7830 9796–013
null character<br />
The ASCII character whose internal value is binary zero.<br />
Glossary<br />
null-terminated<br />
An ASCII character string whose end is indicated by the null character. Any characters<br />
that follow the null character are disregarded. Contrast with space-filled.<br />
O<br />
object module<br />
See absolute element.<br />
omnibus element<br />
A type of element that contains information in a more flexible format than the other<br />
element types provide. The actual format of the data in an omnibus element depends on<br />
the processor that produced it. Omnibus elements are further classified by subtype,<br />
which indicates which system processor produced, or can process, the data within the<br />
element.<br />
owner<br />
P<br />
See file owner.<br />
parameter<br />
In the context of this reference manual, a parameter is a data structure that is passed by<br />
the calling program as information to a PCFP function.<br />
partial string specification<br />
The use of wild-card characters in a character string to specify only a part of a character<br />
value that PCFP must match. Also called partial name specification.<br />
PF<br />
See standard program file.<br />
physical end of volume<br />
The point on a tape volume at which no more data can be read from or written to the<br />
volume. When a tape file reaches this point, a swap must occur before any further data<br />
can be read from or written to the tape file.<br />
physical position<br />
The physical point along a volume of tape at which the read-write heads of the tape unit<br />
are currently positioned.<br />
position<br />
(1) An increment for measuring mass storage space, equal to 64 tracks, 4,096 sectors, or<br />
114,688 words. (2) The current placement of a magnetic tape in relationship to the<br />
read/write heads of the tape unit. See also physical position, logical file position.<br />
7830 9796–013 Glossary–9
Glossary<br />
preamble<br />
A discrete part of a relocatable element that identifies and describes the following<br />
entities within the element: location counters, entry points, and external references. In<br />
addition, the preamble contains other information about the relocatable element that is<br />
used during a collection process involving this element.<br />
prep<br />
privacy<br />
private<br />
The process of building one or both entry point tables in a program file.<br />
The discretionary access control given to a file at the discretion of the owner. The<br />
controls are discretionary in the sense that the file's owner can pass permission (perhaps<br />
indirectly) on to any other user within the mandatory bounds of control. For owned files,<br />
the levels of privacy are private, semiprivate, and public. For unowned files, the privacy<br />
levels are private and public.<br />
One of the levels of privacy for a file. For an owned private file, only the owner can<br />
access the file. For an unowned private file, only a run with the correct account-id or<br />
project-id can access the file.<br />
procedure<br />
A set of statements that is stored apart from a program within a symbolic element, and<br />
is dynamically included with the program when it is compiled or assembled. Procedures<br />
are used most often when the same instructions must be included in different programs.<br />
Four computer languages can use procedures: MASM, COBOL, FORTRAN, and PLUS.<br />
See also copy procedure, include procedure.<br />
procedure symbolic element<br />
One of four symbolic element subtypes that can contain procedures. These subtypes<br />
are ASMP (MASM procedures), COBP (COBOL procedures), FORP (FORTRAN<br />
procedures), and PSP (PLUS procedures).<br />
procedure table<br />
One of three tables in the table of contents of a program file. A procedure table is used<br />
to locate the procedures contained in the program file. Each entry in a procedure table<br />
contains the name of a procedure, the sequence number of the element that contains<br />
the procedure, and the location of the procedure text. One procedure table contains<br />
MASM procedures, one contains COBOL procedures, and one contains FORTRAN and<br />
PLUS procedures.<br />
program file<br />
A partitioned random-access file consisting of a group of elements residing on mass<br />
storage.<br />
project-id<br />
An identifier used to label a run for file access control. It may also classify unowned<br />
files. It is also used as a grouping mechanism within ACRs.<br />
public<br />
One of the levels of privacy for a file. Any user on the system can access a public file.<br />
Glossary–10 7830 9796–013
Q<br />
Glossary<br />
quota group<br />
Under the quota system, a grouping of mass storage equipment types specified by the<br />
site administrator.<br />
R<br />
random-access file (RAF)<br />
A data file that is read randomly. Random-access files operated on by PCFP are<br />
contained on mass storage. Sometimes called a mass storage file.<br />
relative cycle<br />
See F-cycle, element cycle.<br />
relocatable element<br />
A type of element produced by some compilers that contains machine instructions that<br />
must still undergo the process of collection before they can be executed.<br />
return area<br />
An output parameter used by some PCFP functions for the return of a variable-length<br />
array of data structures to the calling program. Each entry in the array returned by PCFP<br />
is called a return entry. The return area parameter is described in the return-information<br />
part of the function packet.<br />
return entry<br />
A single occurrence in the array of information that some PCFP functions return to the<br />
calling program in the return area.<br />
return-information part of function packet<br />
The part of the function packet that describes the return area used by the function. This<br />
part of the function packet is present only for those functions that have a return area<br />
parameter. For those function packets that contain a return-information part, it follows<br />
immediately after the generic part.<br />
S<br />
sector<br />
An increment for measuring mass storage space, equal to 28 words.<br />
sector-addressable<br />
Pertaining to mass storage that can be accessed in units of 28 words (one sector).<br />
security-ownership feature<br />
An Executive feature that assigns ownership to a file based on a user-id access system.<br />
It classifies three types of ownership modes: public, private, and semiprivate. A file with<br />
public ownership is accessible by all users. A file with private ownership is accessible<br />
only by the user that created the file. A file with semiprivate ownership is accessible<br />
only by users named in an ACR.<br />
7830 9796–013 Glossary–11
Glossary<br />
semiprivate<br />
One of the levels of privacy for a file. A semiprivate file has an ACR attached to it. Only<br />
an owned file can be semiprivate. The owner of a semiprivate file has all types of access<br />
to the file. Other users have access to the file depending on the conditions specified in<br />
the ACR.<br />
sequence number<br />
An integer denoting an element's position within a program file. An element whose<br />
sequence number is 3 is described by the third entry in the element table of the program<br />
file.<br />
Sequential-access file (SAF)<br />
A data file that is read sequentially. Sequential-access files operated on by PCFP are<br />
contained on tape. Sometimes called a tape file.<br />
site info<br />
A half-word of information in the MFD entry of a cataloged file, which can be used by a<br />
site in whatever manner it chooses. The information is stored in H2 of word 12 of sector<br />
0 of the MFD main item associated with each cataloged file.<br />
source file<br />
The file from which data is read during a copy operation.<br />
space-filled<br />
An ASCII character string in which the significant characters are followed by a series of<br />
space characters out to the maximum size of the string. Contrast with null-terminated.<br />
specific part of function packet<br />
The part of the function packet that contains items unique to a particular function. This<br />
part of the function packet varies in size depending on the function, and is always the<br />
last part of the function packet.<br />
standard calling sequence (SCS)<br />
A set of standard conventions for compiler programs that controls parameter passing. It<br />
generally eliminates the need for interface routines for programs written in different<br />
compiler languages, allowing an application to be written in several languages. There are<br />
three levels of conformance to the standard calling sequence: none, loose, and strict.<br />
standard program file<br />
A program file format that has small, variable length tables. The element table can<br />
normally contain up to 2,671 elements but can be expanded to contain up to 5,000<br />
elements. Each element can contain up to 262,143 sectors of element text. See also<br />
large element program file, large program file, and program file.<br />
structure<br />
See data structure.<br />
swap<br />
The unmounting of one volume of a sequential-access file followed by the mounting of<br />
another volume. A swap typically occurs when the physical end of a volume of an SAF is<br />
reached during reading or writing of the SAF: after the swap, the read or write operation<br />
continues at the start of the next volume of the SAF. A swap can also result from a<br />
MOVE_SAF operation.<br />
Glossary–12 7830 9796–013
Glossary<br />
symbolic element<br />
A type of element that contains symbolic images. A symbolic element can contain a<br />
source program, directives for a processor, a runstream, or data. The images in a<br />
symbolic element are in system data format (SDF). Symbolic elements are further<br />
classified by subtype, which indicates which system processor produced, or can<br />
process, the images within the element.<br />
symbolic element cycle<br />
See element cycle.<br />
system data format (SDF)<br />
A sequential access, variable record length, file format that is used by 1100/2200 system<br />
software for storage of symbolic data.<br />
T<br />
table of contents (TOC)<br />
A directory within a program file that is used to keep track of elements, entry points, and<br />
procedures within the file. The table of contents consists of six tables: an element table,<br />
three procedure tables, and two entry point tables.<br />
tape<br />
A strip of material used for auxiliary storage. A tape has sequential-access capability as<br />
opposed to, for example, mass storage capability. Includes all types of magnetic tape<br />
subsystems.<br />
tape format<br />
A software convention used to encode the data contained in a logical file on a tape file.<br />
At the present time, PCFP can only read and write logical files using the FURPUR format.<br />
tape labeling<br />
A software system of security labels on a volume of tape specifying the mandatory<br />
attributes (clearance level and compartment set) and the discretionary attributes (access<br />
list) associated with the data stored on the volume.<br />
temporary file<br />
A file that exists only for the duration of the run. When the run terminates or the file is<br />
released from the run, the file ceases to exist. You create a temporary file with the<br />
@ASG,T statement. See also lifetime, cataloged file.<br />
track<br />
An increment for measuring mass storage space. Equal to 1,792 words or 64 sectors.<br />
track sequence number<br />
An integer denoting the location of a track of data stored in a logical file on a tape file.<br />
Track sequence numbers start with 0 for the first track of a logical file, and increase by 1<br />
for each track. Under the FURPUR tape format, the track sequence number of each<br />
track is stored in the track header associated with that track.<br />
7830 9796–013 Glossary–13
Glossary<br />
U<br />
undeleted element<br />
An element in a program file that is not marked as deleted.<br />
user-id<br />
V<br />
A string of 12 characters that is used to identify a person using the system.<br />
value-list item<br />
A data item that can assume a defined set of values with explicit names. For each such<br />
item, the set of values, along with their internal integer codes, are listed in the item<br />
description.<br />
volume<br />
W<br />
One physical unit of storage medium. For magnetic tape, a volume is a reel or a<br />
cartridge. For mass storage, a volume is a disk pack. The volumes that compose a file<br />
are specified when the file is cataloged or assigned.<br />
warning condition<br />
A special situation that was detected during execution of a PCFP function that did not<br />
prevent completion of the function. The nature of the warning is returned as an error<br />
code to the calling program.<br />
wild-card character<br />
One of two special characters that a calling program can specify in certain character<br />
strings it supplies to PCFP. These characters allow partial specification of a string that<br />
PCFP is to match. The question mark character ( ? ) can match any single character. The<br />
asterisk character ( * ) can match any string of zero or more characters.<br />
word<br />
The smallest addressable unit of data, consisting of 36 bits.<br />
word-addressable<br />
Pertaining to mass storage that can be accessed in units of a single word.<br />
work area<br />
A scratch data area used by each PCFP function to perform its operations. The calling<br />
program does not supply the work area for PCFP, as PCFP allocates and releases this<br />
space dynamically. However, the calling program must specify in the function packet the<br />
size of the work area that PCFP allocates.<br />
Glossary–14 7830 9796–013
Z<br />
zero-fill<br />
Glossary<br />
The action of setting an entire data structure or an entire area of mass storage to binary<br />
zero. Zero-filling a PCFP data structure sets each item within the data structure to its<br />
default value.<br />
7830 9796–013 Glossary–15
Glossary<br />
Glossary–16 7830 9796–013
Index<br />
A<br />
acquire basic program file information<br />
(ACQ_BASIC_PF_INFO)<br />
defined, 6-1<br />
parameters, 6-2<br />
structure definition element, 6-3<br />
acquire basic program file item descriptions<br />
COBOL_PROC_NUM_ENTRIES, 6-6<br />
COBOL_PROC_OPEN_ENTRIES, 6-6<br />
DEAD_SPACE, 6-8<br />
ELT_NUM_ENTRIES, 6-6<br />
ELT_OPEN_ENTRIES, 6-6<br />
FTN_PLS_PROC_NUM_ENTRIES, 6-6<br />
FTN_PLS_PROC_OPEN_ENTRIES, 6-7<br />
GET_SUMMARY_INFO, 6-4<br />
LARGEST_UNDELETED_TEXT_ SIZE, 6-8<br />
LATEST_ABS_SEQ_NUM, 6-5<br />
MASM_PROC_NUM_ENTRIES, 6-6<br />
MASM_PROC_OPEN_ENTRIES, 6-6<br />
NEXT_TEXT_LOCATION, 6-5<br />
NUM_4_WORD_COBOL_PROC_ENTRIES,<br />
6-8<br />
NUM_8_WORD_COBOL_PROC_ENTRIES,<br />
6-9<br />
NUM_ABS_ELTS, 6-7<br />
NUM_DELETED_ELTS, 6-8<br />
NUM_OMN_ELTS, 6-7<br />
NUM_PR0C_ELTS, 6-8<br />
NUM_REL_ELTS, 6-7<br />
NUM_SYM_ELTS, 6-7<br />
NUM_UNDELETED_PR0C_ELTS, 6-8<br />
PACK_PF_NUM_ELTS_TO_ UPDATE, 6-9<br />
PACK_PF_TEXT_SIZE_TO_COPY, 6-10<br />
REL_EP_NUM_ENTRIES, 6-7<br />
REL_EP_OPEN_ENTRIES, 6-7<br />
TEXT_SIZE, 6-5<br />
TOC_SIZE, 6-5<br />
acquire element information function<br />
(ACQ_ELT_INFO)<br />
defined, 6-1, 6-11<br />
item descriptions, 6-13<br />
parameters, 6-11<br />
return entry, 6-17<br />
return entry items, 6-18<br />
return entry structure definition<br />
element, 6-17<br />
structure definition element, 6-12<br />
acquire element information function<br />
(ACQ_ELT_INFO) item descriptions<br />
ABS_SUBTYPE, 6-14<br />
ABS_TYPE, 6-13<br />
CHAR_TYPE, 6-14<br />
DELETION, 6-16<br />
ELT_NAME, 6-13<br />
ELT_VERSION, 6-13<br />
INFO_DETAIL, 6-16<br />
MAX_DATE_TIME, 6-15<br />
MAX_SEQ_NUM, 6-15<br />
MAX_SIZE, 6-15<br />
MIN_DATE_TIME, 6-14<br />
MIN_SEQ_NUM, 6-15<br />
MIN_SIZE, 6-15<br />
NUM_SELECTED, 6-16<br />
OMN_SYM_SUBTYPE, 6-14<br />
OMN_TYPE, 6-13<br />
REL_TYPE, 6-13<br />
SYM_TYPE, 6-13<br />
acquire element information function<br />
(ACQ_ELT_INFO) return entry items<br />
ELT_NAME, 6-18<br />
ELT_TYPE, 6-19<br />
ELT_VERSION, 6-18<br />
if ELT_TYPE = ABS, 6-21<br />
if ELT_TYPE = OMN, 6-22<br />
if ELT_TYPE = REL, 6-22<br />
if ELT_TYPE = SYM, 6-23<br />
if INFO_DETAIL = LONG, 6-20<br />
OMN_SYM_SUBTYPE, 6-19<br />
RESULT_INDICATOR, 6-18<br />
SEQ_NUM, 6-19<br />
acquire file information function<br />
(ACQ_FILE_INFO)<br />
C language return entry items, 3-6<br />
COBOL return entry items, 3-34<br />
defined, 3-1<br />
FORTRAN return entry items, 3-34<br />
item descriptions, 3-2<br />
7830 9796–013 Index–1
Index<br />
parameters, 3-1<br />
structure definition element, 3-1<br />
acquire file information function<br />
(ACQ_FILE_INFO) C language return<br />
entry items<br />
cataloged-file part, 3-11<br />
mass storage part, 3-15<br />
nonfloating part, 3-6<br />
run-assignment part, 3-27<br />
security part, 3-25<br />
tape part, 3-19<br />
volume part, 3-26<br />
acquire file information function<br />
(ACQ_FILE_INFO) COBOL return<br />
entry items<br />
CAT_INFO_PRESENT, 3-34<br />
EXTENDED_INFO_PRESENT, 3-34<br />
MASS_STORAGE_INFO_PRESENT, 3-34<br />
RUN_ASG_INFO_PRESENT, 3-35<br />
SECURITY_INFO_PRESENT, 3-34<br />
TAPE_INFO_PRESENT, 3-34<br />
VOL_INFO_PRESENT, 3-35<br />
acquire file information function<br />
(ACQ_FILE_INFO) FORTRAN return<br />
entry items<br />
CAT_INFO_PRESENT, 3-34<br />
EXTENDED_INFO_PRESENT, 3-34<br />
MASS_STORAGE_INFO_PRESENT, 3-34<br />
RUN_ASG_INFO_PRESENT, 3-35<br />
SECURITY_INFO_PRESENT, 3-34<br />
TAPE_INFO_PRESENT, 3-34<br />
VOL_INFO_PRESENT, 3-35<br />
acquire file information function<br />
(ACQ_FILE_INFO) item descriptions<br />
INFO_DETAIL, 3-2<br />
RTN_RUN_ASG_INFO, 3-3<br />
RTN_SECURITY_INFO, 3-3<br />
RTN_VOL_INFO, 3-2<br />
RUN_EQUIP_MNEMONIC, 3-3<br />
acquire file list function (ACQ_FILE_LIST)<br />
defined, 3-36<br />
item descriptions, 3-38<br />
parameters, 3-36<br />
structure definition element, 3-37<br />
acquire file list function (ACQ_FILE_LIST)<br />
item descriptions<br />
ACCOUNT_ID, 3-43<br />
ARC_NAME, 3-43<br />
DIRECTORY_ID, 3-40<br />
EQUIP_TYPE, 3-45<br />
FILE_OWNER_USER_ID, 3-43<br />
FILENAME, 3-41<br />
INFO_DETAIL, 3-38<br />
LIFETIME, 3-40<br />
MAX_CAT_DATE_TIME, 3-44<br />
MAX_CLEARANCE_LEVEL, 3-44<br />
MAX_F_CYCLE, 3-42<br />
MAX_F_CYCLE_TYPE, 3-42<br />
MAX_LAST_REF_DATE_TIME, 3-44<br />
MIN_CAT_DATE_TIME, 3-44<br />
MIN_CLEARANCE_LEVEL, 3-43<br />
MIN_F_CYCLE, 3-42<br />
MIN_F-CYCLE-TYPE, 3-41<br />
MIN_LAST_REF_DATE_TIME, 3-44<br />
NUM_SELECTED, 3-45<br />
PACK_ID, 3-41<br />
PROJECT_ID, 3-43<br />
QUALIFIER, 3-41<br />
RTN_EQUIP_MNEMONIC, 3-40<br />
RTN_RUN_ASG_INFO, 3-39<br />
RTN_SECURITY, 3-39<br />
RTN_VOL_INFO, 3-39<br />
SEARCH_SET, 3-40<br />
SELECT_ON_SITE_INFO, 3-45<br />
SITE_INFO, 3-45<br />
acquire object module entry point<br />
defined, 6-1, 6-29<br />
item descriptions, 6-32<br />
options, 6-30<br />
parameters, 6-30<br />
return entry items, 6-35<br />
return entry structure definition<br />
element, 6-35<br />
structure definition element, 6-31<br />
acquire object module entry point item<br />
descriptions<br />
ELT_NAME, 6-33<br />
ELT_VERSION, 6-34<br />
EP_NAME, 6-34<br />
INFO_DETAIL, 6-32<br />
MAX_COUNT, 6-32<br />
MAX_DATE_TIME, 6-33<br />
MIN_DATE_TIME, 6-33<br />
NUM_SELECTED, 6-34<br />
SCS_CONFORMANCE, 6-33<br />
TEXT_TYPE, 6-32<br />
acquire object module entry point return entry<br />
items<br />
CREATE_DATE_TIME, 6-36<br />
EP_INDEX, 6-35<br />
EP_NAME, 6-37<br />
EP_NAME_LENGTH, 6-37<br />
EP_TYPE, 6-36<br />
long form items, 6-37<br />
PREPPED, 6-37<br />
SEQ_NUM, 6-35<br />
Index–2 7830 9796–013
TEXT_TYPE, 6-36<br />
VISIBILITY, 6-36<br />
acquire procedure information function<br />
(ACQ_PROC_INFO)<br />
COBOL return entry items, 6-45<br />
COBOL structure definition element, 6-44<br />
defined, 6-1, 6-39<br />
item descriptions, 6-40<br />
options, 6-39<br />
parameters, 6-39<br />
return entry items, 6-43<br />
return entry structure definition<br />
element, 6-43<br />
structure definition element, 6-40<br />
acquire procedure information function<br />
(ACQ_PROC_INFO) COBOL return<br />
entry items<br />
DELETE_FLAG, 6-45<br />
ELT_NAME, 6-46<br />
ELT_VERSION, 6-46<br />
PROC_LOCATION, 6-46<br />
PROC_NAME, 6-46<br />
SEQ_NUM, 6-45<br />
TEXT_TYPE, 6-45<br />
acquire procedure information function<br />
(ACQ_PROC_INFO) item descriptions<br />
DELETION, 6-40<br />
ELT_NAME, 6-41<br />
ELT_VERSION, 6-42<br />
INFO_DETAIL, 6-41<br />
MAX_COUNT, 6-41<br />
NUM_SELECTION, 6-42<br />
PROC_NAME, 6-41<br />
PROC_TABLE, 6-41<br />
acquire procedure information function<br />
(ACQ_PROC_INFO) return entry<br />
items<br />
DELETE_FLAG, 6-43<br />
if INFO_DETAIL = LONG, 6-44<br />
PROC_LOCATION, 6-44<br />
PROC_NAME, 6-44<br />
SEQ_NUM, 6-43<br />
TEXT_TYPE, 6-43<br />
acquire relocatable entry point<br />
defined, 6-1, 6-24<br />
item descriptions, 6-25<br />
options, 6-24<br />
parameters, 6-24<br />
return entry items, 6-27<br />
structure definition element, 6-25<br />
acquire relocatable entry point item<br />
descriptions<br />
DELETION, 6-26<br />
Index<br />
ELT_NAME, 6-26<br />
ELT_VERSION, 6-26<br />
EP_NAME, 6-26<br />
INFO_DETAIL, 6-25<br />
MAX_COUNT, 6-25<br />
NUM_SELECTED, 6-27<br />
acquire relocatable entry point return entry<br />
items<br />
DELETE_FLAG, 6-27<br />
ELT_NAME, 6-28<br />
ELT_VERSION, 6-28<br />
EP_NAME, 6-28<br />
SEQ_NUM, 6-28<br />
7830 9796–013 Index–3<br />
B<br />
BUFFON, 3-22<br />
BUFOFF, 3-22<br />
BUFTAP, 3-22, 5-9, 5-29, 10-12<br />
C<br />
C programs<br />
constant name prefixes, 11-3<br />
general PCFP elements, 11-1<br />
handling errors, 11-9<br />
handling warnings, 11-9<br />
include element example, 11-2<br />
include element file, 11-1<br />
include element form, 11-1<br />
include element name, 11-1<br />
include element version, 11-1<br />
naming conventions, 11-2<br />
return entry requirements, 11-10<br />
calling PCFP<br />
examples, 1-3<br />
change element attributes function<br />
(CHG_ELT)<br />
defined, 8-1<br />
item descriptions, 8-3<br />
options, 8-2<br />
parameters, 8-2<br />
change element attributes function<br />
(CHG_ELT) item descriptions<br />
ABS_SUBTYPE, 8-5<br />
ABS_TYPE, 8-4<br />
CHANGE_DATE_TIME, 8-6<br />
CHANGE_SYM_SUBTYPE, 8-6<br />
ELT_NAME, 8-3<br />
ELT_VERSION, 8-4
Index<br />
EXCLUSIVE_ASSIGN, 8-6<br />
INFO_DETAIL, 8-8<br />
INFO_TO_RETURN, 8-8<br />
NEW_CYCLE_LIMIT, 8-7<br />
NEW_ELT_NAME, 8-5<br />
NEW_ELT_VERSION, 8-5<br />
NEW_OMN_SYM_SUBTYPE, 8-7<br />
NUM_FAILED, 8-9<br />
NUM_SELECTED, 8-8<br />
NUM_SUCCESSFUL, 8-9<br />
OMN_SYM_SUBTYPE, 8-5<br />
OMN_TYPE, 8-4<br />
PROCEED_ON_CONFLICT, 8-6<br />
REL_TYPE, 8-4<br />
SYM_TYPE, 8-4<br />
change file cycle attributes function<br />
(CHG_FILE_CYC)<br />
defined, 4-1, 4-7<br />
item descriptions, 4-8<br />
options, 4-7<br />
parameters, 4-8<br />
structure definition element, 4-8<br />
change file cycle attributes function<br />
(CHG_FILE_CYC) item descriptions<br />
ALLOW_DELETION, 4-8<br />
F_CYCLES_DELETED, 4-9<br />
F_CYCLES_RETAINED, 4-9<br />
MAX_F_CYCLES, 4-8<br />
change file keys function (CHG_FILE_KEY)<br />
item descriptions<br />
READ_KEY, 4-14<br />
WRITE_KEY, 4-14<br />
change file keys function (CHG_FILE_KEYS)<br />
defined, 4-1, 4-13<br />
parameters, 4-13<br />
structure definition element, 4-13<br />
change file security attributes function<br />
(CHG_FILE_SEC)<br />
defined, 4-1, 4-10<br />
item descriptions, 4-11<br />
parameters, 4-10<br />
structure definition element, 4-11<br />
change file security attributes function<br />
(CHG_FILE_SEC) item descriptions<br />
ACR_NAME, 4-12<br />
CHG_CLEARANCE_LEVEL, 4-11<br />
CHG_FILE_OWNER, 4-11<br />
CLEARANCE_LEVEL, 4-11<br />
FILE_OWNER_USER_ID, 4-12<br />
PRIVACY, 4-12<br />
change file specific attributes function<br />
(CHG_FILE)<br />
defined, 4-1<br />
item descriptions, 4-3<br />
structure definition element, 4-2<br />
change file specific attributes function<br />
(CHG_FILE) item descriptions<br />
ACCOUNT_ID, 4-3<br />
BACKUP_DISABLE, 4-5<br />
CACHE_DISABLE, 4-5<br />
CHG_SITE_INFO, 4-6<br />
DIRECTORY_DISABLE, 4-4<br />
INIT_PROGRAM_FILE, 4-3<br />
PROJECT_ID, 4-3<br />
READ_ONLY, 4-5<br />
ROLLOUT_PROHIBITED, 4-3<br />
SITE_INFO, 4-6<br />
WRITE_DISABLE, 4-4<br />
WRITE_ONLY, 4-6<br />
changing file attributes, See change file<br />
function; change file keys function;<br />
change file specific<br />
character, defined, 2-3<br />
close SAF function (CLOSE_SAF)<br />
item description, FORMAT, 10-13<br />
structure definition element, 10-13<br />
COBOL reserved word<br />
DAY, 2-4<br />
PF, 12-4<br />
TAPE, 12-4<br />
comparing date-time values, 2-4<br />
condition, defined, 2-3<br />
copy element function (COPY_ELT)<br />
copying object modules, 7-2<br />
copying relocatable elements, 7-2<br />
defined, 7-1<br />
item descriptions, 7-4<br />
options, 7-1<br />
parameters, 7-1, 7-2<br />
structure definition element, 7-3<br />
copy element function (COPY_ELT) item<br />
descriptions<br />
ABS_SUBTYPE, 7-5<br />
ABS_TYPE, 7-4<br />
CYCLE_NUM, 7-8<br />
CYCLE_TYPE, 7-7<br />
DEST_ELT_NAME, 7-6<br />
DEST_ELT_VERSION, 7-6<br />
ELT_NAME, 7-4<br />
ELT_VERSION, 7-4<br />
EXCLUSIVE_ASSIGN, 7-6<br />
INFO_DETAIL, 7-8<br />
INFO_TO_RETURN, 7-8<br />
NEW_DATE_TIME, 7-6<br />
NUM_FAILED, 7-9<br />
NUM_SELECTED, 7-9<br />
Index–4 7830 9796–013
NUM_SUCCESSFUL, 7-9<br />
OMN_SYM_SUBTYPE, 7-5<br />
OMN_TYPE, 7-4<br />
ON_CONFLICT, 7-7<br />
REL_TYPE, 7-4<br />
SYM_TYPE, 7-4<br />
copy omnibus element to RAF function<br />
(COPY_OMN_ELT_RAF)<br />
defined, 7-21<br />
item descriptions, 7-22<br />
parameters, 7-21<br />
structure definition element, 7-21<br />
copy omnibus element to RAF function<br />
(COPY_OMN_ELT_RAF) item<br />
descriptions<br />
AMOUNT_COPIED, 7-22<br />
ELT_NAME, 7-22<br />
ELT_VERSION, 7-22<br />
PREVENT OVERCOPY, 7-22<br />
copy RAF to omnibus element function<br />
(COPY_RAF_OMN_ELT)<br />
defined, 7-23<br />
item descriptions, 7-24<br />
options, 7-23<br />
parameters, 7-23<br />
structure definition element, 7-24<br />
copy RAF to omnibus element function<br />
(COPY_RAF_OMN_ELT) item<br />
descriptions<br />
AMOUNT_COPIED, 7-26<br />
DEST_ELT_NAME, 7-24<br />
DEST_ELT_VERSION, 7-24<br />
DEST_OMN_SUBTYPE, 7-25<br />
EXCLUSIVE_ASSIGN, 7-26<br />
ON_CONFLICT, 7-26<br />
copy RAF to RAF function (COPY_RAF_RAF)<br />
defined, 5-1<br />
item descriptions, 5-2<br />
options, 5-1<br />
parameters, 5-2<br />
structure definition element, 5-2<br />
copy RAF to RAF function (COPY_RAF_RAF)<br />
item descriptions<br />
AMOUNT_COPIED, 5-3<br />
PREVENT_OVERCOPY, 5-2<br />
STORAGE_TO_RELEASE, 5-3<br />
ZERO_RELEASED_STORAGE, 5-2<br />
copy RAF to SAF function (COPY_RAF_SAF)<br />
defined, 5-1, 5-4<br />
item descriptions, 5-8<br />
options, 5-4<br />
return entry items, 5-12<br />
Index<br />
copy RAF to SAF function (COPY_RAF_SAF)<br />
item descriptions<br />
AMOUNT_COPIED, 5-10<br />
DEST_BLOCK_SIZE, 5-9<br />
DEST_FORMAT, 5-9<br />
OMIT_LOG_END_MARK, 5-8<br />
ON_END_OF_DEST_FILE, 5-10<br />
SAVE_CHECKSUMS, 5-8<br />
WRITE_OBSOLETE_VARIANT, 5-8<br />
copy RAF to SAF function (COPY_RAF_SAF)<br />
return entry items<br />
ENTRY_SIZE, 5-12<br />
FRAGMENT_SIZE, 5-13<br />
LOGICAL_FILE_POSITION, 5-12<br />
NUM_VOLS, 5-12<br />
RESULT_INDICATOR, 5-12<br />
VOL_ID, 5-13<br />
copy RAF to SAF function (COPY_RAF_SAF)<br />
structure definition element, 5-7<br />
copy RAF to symbolic element<br />
(COPY_RAF_SYM_ELT)<br />
defined, 7-17<br />
item descriptions, 7-18<br />
options, 7-17<br />
parameters, 7-17<br />
structure definition element, 7-18<br />
copy RAF to symbolic element<br />
(COPY_RAF_SYM_ELT) item<br />
descriptions<br />
AMOUNT_COPIED, 7-20<br />
DEST_ELT_VERSION, 7-18<br />
DEST_SYM_ELT, 7-18<br />
DEST_SYM_SUBTYPE, 7-19<br />
EXCLUSIVE_ASSIGN, 7-20<br />
ON_CONFLICT, 7-20<br />
copy SAF to RAF function (COPY_SAF_RAF)<br />
defined, 5-1, 5-14<br />
item descriptions, 5-17<br />
options, 5-14<br />
parameters, 5-16<br />
return entry items, 5-21<br />
structure definition element, 5-16<br />
copy SAF to RAF function (COPY_SAF_RAF)<br />
item descriptions<br />
AMOUNT_COPIED, 5-19<br />
DESC_RTN_AREA_SIZE, 5-19<br />
LOC_FIRST_CHECKSUM_ERROR, 5-19<br />
LOC_FIRST_TRACK_SEQ_ERROR, 5-19<br />
NUM_CHECKSUM_ERRORS, 5-19<br />
NUM_DEST_FILES, 5-18<br />
NUM_TRACK_SEQ_ERRORS, 5-19<br />
ON_END_OF_SOURCE_FILE, 5-18<br />
PREVENT_OVERCOPY, 5-17<br />
7830 9796–013 Index–5
Index<br />
PROCESS_CHECKSUM_ERRORS, 5-17<br />
PROCESS_TRACK_SEQ_ERRORS, 5-17<br />
STORAGE_TO_RELEASE, 5-18<br />
ZERO_RELEASED_STORAGE, 5-17<br />
copy SAF to RAF function (COPY_SAF_RAF)<br />
return entry items<br />
BLOCK_SIZE, 5-21<br />
DATE_TIME_COPIED, 5-22<br />
F_CYCLE, 5-23<br />
F_CYCLE_TYPE, 5-23<br />
FILENAME, 5-22<br />
FORMAT, 5-21<br />
HIGHEST_WORD_WRITTEN, 5-23<br />
LOGICAL_FILE_POSITION, 5-22<br />
QUALIFIER, 5-22<br />
VOL_ID, 5-21<br />
copy SAF to SAF function (COPY_SAF_SAF)<br />
defined, 5-1, 5-24<br />
item descriptions, 5-28<br />
options, 5-24<br />
parameters, 5-26<br />
return entry items, 5-12<br />
structure definition element, 5-27<br />
copy SAF to SAF function (COPY_SAF_SAF)<br />
item descriptions<br />
AMOUNT_COPIED, 5-31<br />
DESC_RTN_AREA_SIZE, 5-30<br />
DEST_BLOCK_SIZE, 5-30<br />
LOC_FIRST_CHECKSUM_ERROR, 5-32<br />
LOC_FIRST_TRACK_SEQ_ERROR, 5-32<br />
NUM_CHECKSUM_ERRORS, 5-31<br />
NUM_DEST_FILES, 5-29<br />
NUM_TRACK_SEQ_ERRORS, 5-32<br />
OMIT_LOG_END_MARK, 5-28<br />
ON_END_OF_DEST_FILE, 5-31<br />
ON_END_OF_SOURCE_FILE, 5-30<br />
PROCESS_CHECKSUM_ERRORS, 5-28<br />
PROCESS_TRACK_SEQ_ERRORS, 5-28<br />
SAVE_CHECKSUMS, 5-29<br />
WRITE_OBSOLETE_VARIANT, 5-29<br />
copy SAF to SAF function (COPY_SAF_SAF)<br />
return entry items<br />
ENTRY_SIZE, 5-12<br />
FRAGMENT_SIZE, 5-13<br />
LOGICAL_FILE_POSITION, 5-12<br />
NUM_VOLS, 5-12<br />
RESULT_INDICATOR, 5-12<br />
VOL_ID, 5-13<br />
copy symbolic element to RAF<br />
(COPY_SYM_ELT_RAF)<br />
defined, 7-14<br />
item descriptions, 7-15<br />
options, 7-14<br />
parameters, 7-14<br />
structure definition element, 7-15<br />
copy symbolic element to RAF<br />
(COPY_SYM_ELT_RAF) item<br />
descriptions<br />
ACTION, 7-15<br />
AMOUNT_COPIED, 7-16<br />
CYCLE_NUM, 7-16<br />
CYCLE_TYPE, 7-16<br />
ELT_NAME, 7-15<br />
ELT_VERSION, 7-15<br />
create program file entry point table function<br />
(PREP_PF)<br />
defined, 8-36<br />
item descriptions, 8-37<br />
options, 8-36<br />
parameters, 8-36<br />
structure definition element, 8-37<br />
create program file entry point table function<br />
(PREP_PF) item descriptions<br />
DUP_REL_EP_CNT, 8-38<br />
EP_TYPE, 8-37<br />
OM_EP_CNT, 8-38<br />
OVERWRITE_OLD_EP_TABLE, 8-37<br />
REL_EP_CNT, 8-37<br />
Index–6 7830 9796–013<br />
D<br />
data type definitions<br />
character, 2-3<br />
condition, 2-3<br />
date-time, 2-4<br />
integer, 2-3<br />
value-list, 2-4<br />
date-time, defined, 2-4<br />
DAY, COBOL reserved word, 2-4<br />
delete elements function (DELETE_ELT)<br />
defined, 8-10<br />
item descriptions, 8-12<br />
options, 8-10<br />
parameters, 8-11<br />
structure definition element, 8-11<br />
delete elements function (DELETE_ELT) item<br />
descriptions<br />
ABS_SUBTYPE, 8-13<br />
ABS_TYPE, 8-12<br />
ALL_INFO, 8-13<br />
ELT_NAME, 8-12<br />
ELT_VERSION, 8-12<br />
EXCLUSIVE_ASSIGN, 8-13<br />
INFO_DETAIL, 8-14
INFO_TO_RETURN, 8-13<br />
NUM_SELECTED, 8-14<br />
OMN_SYM_SUBTYPE, 8-13<br />
OMN_TYPE, 8-12<br />
REL_TYPE, 8-12<br />
SYM_TYPE, 8-12<br />
delete file function (DELETE_FILE)<br />
defined, 9-4<br />
item descriptions, 9-5<br />
options, 9-4<br />
parameters, 9-4<br />
structure definition element, 9-5<br />
delete file function (DELETE_FILE) item<br />
descriptions<br />
EXCLUSIVE_ASSIGN, 9-5<br />
ZERO_RELEASED_STORAGE, 9-5<br />
deleting a file, See delete file function<br />
directory-id, unique file identifier, 2-4<br />
E<br />
EOF mark, 5-24<br />
erase RAF function (ERASE_RAF)<br />
defined, 9-1<br />
item descriptions, 9-2<br />
options, 9-1<br />
parameters, 9-2<br />
structure definition element, 9-2<br />
erase RAF function (ERASE_RAF) item<br />
descriptions<br />
STORAGE_RELEASED, 9-3<br />
STORAGE_TO_RELEASE, 9-3<br />
ZERO_RELEASED_STORAGE, 9-2<br />
ZERO_RETAINED_STORAGE, 9-3<br />
erasing files, See erase RAF function<br />
examples<br />
ACQ_ELT_INFO, 1-14<br />
C calling PCFP functions, 11-15, 11-16,<br />
11-17<br />
calling PCFP, 1-3<br />
COBOL calling PCFP functions, 12-10,<br />
12-11, 12-14<br />
COPY_RAF_RAF, 1-9<br />
declaring a return area, 11-11<br />
DELETE_FILE, 1-3<br />
FORTRAN calling PCFP functions, 13-11,<br />
13-12<br />
handling date-time items, 11-10, 12-7<br />
setting items in a bit array, 11-9<br />
using MOVE statement with PCFP, 12-6<br />
examples handling date-time items<br />
C, 11-10<br />
COBOL, 12-7<br />
Index<br />
7830 9796–013 Index–7<br />
F<br />
fast tape access, 5-13, 5-22, 10-1, 10-5,<br />
10-10, 10-14<br />
F-cycle, unique file identifier, 2-4<br />
file identifier<br />
defined, 2-2<br />
structure defined, 2-5<br />
file identifier packet<br />
item descriptions, 2-6<br />
file identifier packet item descriptions<br />
DIRECTORY_ID, 2-6<br />
F_CYCLE, 2-7<br />
F_CYCLE_TYPE, 2-7<br />
FILENAME, 2-6<br />
INTERFACE_LEVEL, 2-6<br />
QUALIFIER, 2-6<br />
READ_KEY, 2-7<br />
WRITE_KEY, 2-7<br />
file identity<br />
initialization of, 2-5<br />
items for uniqueness, 2-4<br />
unique identifier<br />
directory-id, 2-4<br />
F-cycle, 2-4<br />
F-cycle type, 2-4<br />
file name, 2-4<br />
interface level number, 2-4<br />
qualifier, 2-4<br />
read/write keys, 2-4<br />
file information, See acquire file information<br />
function; acquire file list function<br />
file name, unique file identifier, 2-4<br />
file types, 1-2<br />
FORTRAN examples, 13-9<br />
FORTRAN program examples<br />
copying a file, 13-11<br />
deleting a file, 13-10<br />
FORTRAN programs<br />
compiling with PCFP, 13-9<br />
function names, 13-4<br />
handling errors, 13-9<br />
handling warnings, 13-9<br />
item names within packets, 13-4<br />
naming conventions, 13-4<br />
packet names, 13-4<br />
PCFP constants defined, 13-4
Index<br />
procedure descriptions, 13-1<br />
procedure file, 13-1<br />
procedure names, 13-1<br />
function packet<br />
defined, 2-2<br />
return-information part item<br />
descriptions, 2-13<br />
function packet generic part item descriptions<br />
AUX_ERROR_CODE, 2-12<br />
ERROR_CLASS, 2-11<br />
ERROR_FILE, 2-11<br />
GEN_DATE_TIME, 2-10<br />
NULL_TERM_STRINGS, 2-10<br />
QUESTION_MARK_MATCHES_SPACE, 2-<br />
10<br />
SOFTWARE_LEVEL, 2-10<br />
WAIT_ON_FACILITIES, 2-10<br />
WORK_AREA_SIZE, 2-10<br />
function packet return-information part item<br />
descriptions<br />
NUM_RTN_ENTRIES, 2-13<br />
NUMB_ENTRIES_IN_RTN_AREA, 2-14<br />
RTN_AREA-SIZE, 2-13<br />
RTN_ENTRY-SIZE, 2-14<br />
function parameters<br />
file identifier, 2-2<br />
function packet, 2-2<br />
return area, 2-2<br />
work area, 2-2<br />
functions<br />
aspects of, 2-16<br />
file identification, 2-4<br />
general form of, 2-1<br />
parameters used by most functions, 2-1,<br />
2-2<br />
successful completion of, 2-2<br />
value returned, 2-2<br />
G<br />
generation date and time, PCFP<br />
processor, 1-23<br />
I<br />
integer, defined, 2-3<br />
item descriptions, See data type definitions<br />
Index–8 7830 9796–013<br />
L<br />
level, PCFP processor, 1-23<br />
M<br />
move SAF function (MOVE_SAF)<br />
defined, 10-1<br />
item descriptions, 10-4<br />
options, 10-1<br />
parameters, 10-2<br />
structure definition element, 10-3<br />
move SAF function (MOVE_SAF) item<br />
descriptions<br />
CURRENT_VOL_ONLY, 10-4<br />
INTERLOCK, 10-4<br />
LOGICAL_FILE_POSITION, 10-7<br />
MOVE_NUM, 10-6<br />
NUM_FILES_MOVED, 10-6<br />
ON_END_OF_FILE, 10-6<br />
POSITION_AT_END_OF_LOG_FILE, 10-4<br />
TYPE_OF_MOVE, 10-5<br />
VOL_ID, 10-7<br />
O<br />
object module entry point table<br />
option not specified, 8-36<br />
removal of object module, 8-10<br />
removal of relocatable, 8-2<br />
P<br />
pack program file function (PAK_PF)<br />
item descriptions, 8-26<br />
structure definition element, 8-26<br />
pack program file function (PAK_PF) item<br />
descriptions<br />
COBOL_PROC_NUM_ENTRIES, 8-29<br />
COBOL_PROC_OPEN_ENTRIES, 8-29<br />
DEAD_SPACE, 8-30<br />
ELT_NUM_ENTRIES, 8-28<br />
ELT_OPEN_ENTRIES, 8-28<br />
FTN_PLS_PROC_NUM_ENTRIES, 8-29<br />
FTN_PLS_PROC_OPEN_ENTRIES, 8-29<br />
LATEST_ABS_SEQ_NUM, 8-28<br />
MASM_PROC_NUM_ENTRIES, 8-29<br />
MASM_PROC_OPEN_ENTRIES, 8-29
NEXT_TEXT_LOCATION, 8-28<br />
NUM_ABS_ELTS, 8-30<br />
NUM_DELETED_ELTS, 8-30<br />
NUM_OMN_ELTS, 8-30<br />
NUM_REL_ELTS, 8-30<br />
NUM_SYM_ELTS, 8-30<br />
REL_EP_NUM_ENTRIES, 8-29<br />
REL_EP_OPEN_ENTRIES, 8-30<br />
STORAGE_TO_RELEASE, 8-27<br />
TEXT_SIZE, 8-28<br />
TOC_SIZE, 8-28<br />
ZERO_RELEASED_STORAGE, 8-26<br />
PCFP<br />
acquire element information example, 1-14<br />
copy example, 1-9<br />
DELETE_FILE example, 1-3<br />
design, 1-1<br />
file types, 1-2<br />
function parameters, 2-2<br />
processor generation date and time, 1-23<br />
processor level, 1-23<br />
PF, COBOL reserved word, 12-4<br />
positioning tape files, See move SAF<br />
function<br />
programming languages<br />
C examples, 11-14<br />
COBOL examples, 12-9<br />
special considerations for, 2-1<br />
Q<br />
qualifier, unique file identifier, 2-4<br />
R<br />
return area, defined, 2-2<br />
S<br />
SYNCHRONIZE, 5-9, 5-29, 10-14<br />
T<br />
TAPE, COBOL reserved word, 12-4<br />
Index<br />
7830 9796–013 Index–9<br />
U<br />
undelete elements function (UNDELETE_ELT)<br />
defined, 8-15<br />
options, 8-16<br />
undelete elements function (UNDELETE_ELT)<br />
item descriptions<br />
ABS_SUBTYPE array (0<br />
17), 8-19<br />
ABS_TYPE, 8-18<br />
ALLOW_DELETION, 8-19<br />
ELT_NAME, 8-17<br />
ELT_VERSION, 8-18<br />
EXCLUSIVE_ASSIGN, 8-19<br />
FP_ERR_NONE, 8-22<br />
FP_INFO_PROC_TBL_ERR, 8-22<br />
FP_WARN_ELT_DELETE_NOT_ALLOWED<br />
, 8-22<br />
FP_WARN_ELT_REL_SEQ_NUM_ERR, 8-2<br />
2<br />
FP_WARN_ELT_UNDELETED, 8-22<br />
INFO_DETAIL, 8-20<br />
INFO_TO_RETURN, 8-20<br />
NUM_FAILED, 8-21<br />
NUM_SELECTED, 8-21<br />
NUM_SUCCESSFUL, 8-21<br />
OMN_SYM_SUBTYPE array (0<br />
71), 8-18<br />
OMN_TYPE, 8-18<br />
REL_TYPE, 8-18<br />
SEQ_NUM, 8-20<br />
SEQ_NUM_TYPE, 8-19<br />
SYM_TYPE, 8-18<br />
updating program files, See change element<br />
attributes function; delete elements<br />
function; pack program file function;<br />
create program file entry point table<br />
function<br />
using a bit array, 12-7<br />
V<br />
value-list, defined, 2-4<br />
W<br />
wild-card characters<br />
defined, 2-15<br />
examples of use, 2-15<br />
work area, defined, 2-2, 2-14
Index<br />
Index–10 7830 9796–013
© 2008 <strong>Unisys</strong> Corporation.<br />
All rights reserved.<br />
*78309796-013*<br />
7830 9796–013