(SYSLIB) Programming Reference Manual - Public Support Login ...

OS 2200
System Service Routines Library
(SYSLIB)
Programming Reference Manual
û 2001 Unisys Corporation.
All rights reserved.
ClearPath OS 2200 Release 7.0
Printed in USA
November 2001 7833 1733–004
UNISYS

NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THIS DOCUMENT. Any product or related information
described herein is only furnished pursuant and subject to the terms and conditions of a duly executed agreement to
purchase or lease equipment or to license software. The only warranties made by Unisys, if any, with respect to the
products described in this document are set forth in such agreement. Unisys cannot accept any financial or other
responsibility that may be the result of your use of the information in this document or software material, including
direct, special, or consequential damages.
You should be very careful to ensure that the use of this information and/or software material complies with the laws,
rules, and regulations of the jurisdictions with respect to which it is used.
The information contained herein is subject to change without notice. Revisions may be issued to advise of such
changes and/or additions.
Notice to Government End Users: The software and accompanying documentation are delivered and licensed as
“commercial computer software” and “commercial computer software documentation” as those terms are used in 48
C.F.R. § 12.212 and 48 C.F.R. § 227.7202-1 through 227.7202-4, as applicable. The Government shall receive only those
rights provided in the standard commercial software license, or where applicable, the restricted and limited rights
provisions of the contract FAR or DFARS (or equivalent agency) clause.
Correspondence regarding this publication can be e-mailed to doc@unisys.com.
Unisys and ClearPath are registered trademarks of Unisys Corporation.
All other marks are acknowledged to be the trademarks or registered trademarks of their respective owners. Unisys
Corporation cannot attest to the accuracy of this information.

OS 2200
System Service Routines
Library (SYSLIB)
Programming Reference
Manual
ClearPath OS 2200
Release 7.0
OS 2200
System Service
Routines Library
(SYSLIB)
Programming
Reference
Manual
ClearPath OS 2200
Release 7.0
7833 1733–004 7833 1733–004
Bend here, peel upwards and apply to spine.

Contents
Section 1. Introduction.......................................................................1–1
1.1. About This Manual ................................................................... 1–1
1.2. Notation Conventions............................................................... 1–2
1.3. About SYSLIB........................................................................... 1–4
Section 2. System Standard Procedures and Definitions ...................2–1
2.1. Common Bank Entry Points ..................................................... 2–1
2.2. MAXR$–Register and Partial-Word Definitions........................ 2–2
2.3. PROC$–System Procedures .................................................... 2–4
2.4. SSTYP$–Element Subtypes ..................................................... 2–4
2.5. ASUBTYP$–Executable Element Subtypes and Subsubtypes...............................................................................
2–7
2.6. SYS$DEF–System Definitions.................................................. 2–8
2.7. SYSLIB$ID–SYSLIB Identification ............................................ 2–9
Section 3. SYSLIB Access Methods ....................................................3–1
3.1. Relocatable Collection Method ................................................ 3–2
3.2. Common Bank Call Using I$BJ ................................................ 3–3
3.3. Common Bank Call Using Auto Switch Method ...................... 3–5
Section 4. AEDIT$–ASCII Image Composition Editing Package..........4–1
4.1. Packet....................................................................................... 4–2
4.1.1. Packet Format.................................................................. 4–3
4.1.2. Packet Generation PROC ................................................ 4–4
4.1.3. Examples ......................................................................... 4–5
4.2. Calling Sequence...................................................................... 4–6
4.2.1. General-Purpose Editing Routines................................... 4–7
4.2.2. Floating-Point Editing Routines...................................... 4–14
4.2.2.1. Calling Procedures for the Floating-Point
Editing Routines ............................................... 4–16
4.2.2.2. Example ................................................................ 4–17
4.2.3. Time and Date Editing Routines .................................... 4–18
4.2.4. Standard Format Date and Time Editing Routines ........ 4–19
4.2.4.1. Recommended Date and Time Formats............... 4–21
4.2.4.2. Calling Procedure for Date and Time Editing........ 4–21
4.2.4.3. Example ................................................................ 4–23
7833 1733–004 iii

Contents
4.2.5. Error Status Codes ........................................................ 4–24
4.2.6. Examples....................................................................... 4–25
Section 5. BSP$–Program File Basic Service Package ....................... 5–1
5.1. BSP$ Functions........................................................................ 5–3
5.1.1. Read FTI .......................................................................... 5–3
5.1.2. Read Program File Table ................................................. 5–9
5.1.3. Search Table for Requested Item ................................. 5–11
5.1.4. Delete Item from Requested Table............................... 5–14
5.1.5. Entry Look-Up by Number............................................. 5–18
5.1.6. Change Item in Requested Table.................................. 5–21
5.1.7. Add Item to Requested Table ....................................... 5–23
5.1.8. Write Last Item Referenced.......................................... 5–29
5.1.9. Mark Item as Updated................................................... 5–30
5.1.10. Write Requested Table Back to Mass Storage ............. 5–32
5.1.11. Write FTI........................................................................ 5–33
5.2. Example of Using BSP$ ......................................................... 5–34
5.3. LEPF Considerations.............................................................. 5–35
Section 6. CABSAD$, CRELAD$–Addressing Routines ...................... 6–1
6.1. Absolute Addressing Routines................................................. 6–1
6.1.1. CABSAD$–Compute Absolute Address.......................... 6–2
6.1.2. CAINIT$–Initialize CABSAD$........................................... 6–4
6.1.3. CBX$–Compute Bank Descriptor Index .......................... 6–5
6.1.4. CSX$–Compute Segment Index ..................................... 6–6
6.1.5. CSYMVL$–Compute Symbol Value ................................ 6–7
6.2. Relocatable Addressing Routines ............................................ 6–8
6.2.1. CRELAD$–Compute Relative Address............................ 6–9
6.2.2. CRINIT$–Initialize CRELAD$ ......................................... 6–12
6.2.3. CBN$–Convert BDI to Symbolic Bank Name................ 6–13
6.2.4. CSN$–Convert Segment Index to Segment
Name......................................................................... 6–14
Section 7. CONWRD$–Condition Word Routine ................................. 7–1
7.1. MASM Interface ...................................................................... 7–1
7.2. PLUS Interface......................................................................... 7–3
Section 8. EDIT$–Fieldata Image Composition Editing Package........ 8–1
8.1. EDIT$–Packet Format .............................................................. 8–2
8.2. EDIT$–General-Purpose Editing Routines ............................... 8–5
8.3. EDIT$T–Time and Date Editing Routines................................. 8–8
8.4. EDIT$F–Floating-Point Editing Routines .................................. 8–9
iv 7833 1733–004

Contents
Section 9. FDASC$–Fieldata/ASCII Data Conversion ..........................9–1
9.1. MASM Interface....................................................................... 9–1
9.1.1. Fieldata to ASCII Conversion........................................... 9–1
9.1.2. ASCII to Fieldata Conversion........................................... 9–3
9.2. TABLE$–Fieldata/ASCII Conversion Table ............................... 9–3
Section 10. GETPSF$–Get a Scratch File Routine ...............................10–1
10.1. File Assignment...................................................................... 10–1
10.2. MASM Interface..................................................................... 10–2
10.2.1. Packet............................................................................ 10–2
10.2.2. Calling Sequence ........................................................... 10–2
Section 11. ID$–Identification Line Routine .......................................11–1
11.1. MASM Interface..................................................................... 11–2
11.1.1. Packet............................................................................ 11–2
11.1.2. Calling Sequence ........................................................... 11–5
11.1.3. Examples ....................................................................... 11–7
11.2. PLUS Interface ....................................................................... 11–8
11.2.1. Packet............................................................................ 11–8
11.2.2. Calling Sequence ........................................................... 11–8
11.2.3. Example ....................................................................... 11–11
11.3. Packet Format ...................................................................... 11–12
Section 12. INFOR$–Internal Format Table Interface Routines ...........12–1
12.1. Format of the Internal Format Table ...................................... 12–2
12.2. General Considerations for Using the INFOR Routines ......... 12–2
12.3. INFOR$–Routines................................................................... 12–3
12.3.1. RINF$–Read INFOR Table ............................................. 12–4
12.3.2. SINF$–Search INFOR Table........................................... 12–6
12.3.3. SELT$–Transfer to ELT$ Table from INFOR Table........ 12–8
12.3.4. DUSE$–Assign a USE Name to the File in ELT$......... 12–11
Section 13. MFDSP$–Master File Directory Service Package .............13–1
13.1. Packet..................................................................................... 13–1
13.2. Calling Sequence.................................................................... 13–2
13.3. Error Conditions...................................................................... 13–5
13.4. Examples................................................................................ 13–9
Section 14. PREPRM, PREPRO, PREPF$, and POSTPR$......................14–1
14.1. PREPRO, PREPRM–Preprocessor Routines.......................... 14–1
14.1.1. PREPRO–Preprocessor Routine .................................... 14–2
14.1.2. PREPRM–Preprocessor Routine ................................... 14–3
14.1.3. PARTBL Description ...................................................... 14–5
7833 1733–004 v

Contents
14.1.4. Reusable Processor Construction ................................. 14–7
14.1.4.1. REPRO$–Reusable Processor Preprocessor
Routine ............................................................. 14–8
14.1.4.2. REPRM$–Reusable Processor
Preprocessor Routine....................................... 14–9
14.1.5. FLDGET–Processor Field Retrieval ............................. 14–10
14.2. PREPF$–Preprocessor Routine............................................ 14–12
14.3. POSTPR$–Postprocessor Routine....................................... 14–14
14.4. FLDREL$–Field Release....................................................... 14–14
Section 15. ROR, ROR$–Relocatable Output Routine......................... 15–1
15.1. SROR$, SROR$EB–Start Relocatable Output
Routine .............................................................................. 15–1
15.2. ROR$, ROR$EB–Generation of Relocatable
Output................................................................................ 15–2
15.3. EROR$, EROR$EB–End Relocatable Output
Routine .............................................................................. 15–6
15.4. TBLWR$, TBLWR$EB–Write Table to File ............................ 15–6
15.5. Optimization Information ....................................................... 15–7
Section 16. SAR$–Symbolic Access Routines.................................... 16–1
16.1. File Information Packet .......................................................... 16–2
16.1.1. PLUS Interface .............................................................. 16–2
16.1.1.1. FIP Field Descriptions........................................... 16–2
16.1.1.2. READ and WRITE Field Requirements................. 16–6
16.1.2. MASM Interface............................................................ 16–7
16.1.2.1. FIP Field Descriptions........................................... 16–7
16.1.2.2. READ and WRITE Field Requirements............... 16–11
16.2. SAR$ Internal Format........................................................... 16–12
Section 17. SAR$ READ..................................................................... 17–1
17.1. READ Function/PLUS Interface ............................................. 17–1
17.1.1. READ Packet Data Structure Description ..................... 17–1
17.1.1.1. Required Information for READ Procedures ........ 17–2
17.1.1.2. Optional Information for READ Procedures ......... 17–3
17.1.1.3. Information Returned by READ Procedures......... 17–6
17.1.2. Buffers and Tables for PLUS READ Procedures......... 17–10
17.1.3. READ Procedures Called from PLUS .......................... 17–12
17.1.3.1. SAR_OPEN_INPUT Procedure Call .................... 17–13
17.1.3.2. SAR_READ Procedure Call ................................. 17–14
17.1.3.3. SAR_CLOSE_INPUT Procedure Call................... 17–15
17.1.3.4. Example .............................................................. 17–16
17.1.4. Status Lists for PLUS READ Procedures .................... 17–17
17.2. READ Function/MASM Interface......................................... 17–20
17.2.1. READ Packet and Data Area Description .................... 17–20
17.2.1.1. Required Information for READ Procedures ...... 17–20
17.2.1.2. Optional Information for READ Procedures ....... 17–21
vi 7833 1733–004

Contents
17.2.1.3. Information Returned by READ Procedures....... 17–23
17.2.1.4. READ Packet Definition PROC ........................... 17–26
17.2.2. Buffers and Tables for MASM READ Procedures....... 17–27
17.2.3. READ Procedures Called from MASM........................ 17–27
17.2.3.1. Open-Input Procedure Call (S$AROPENI)........... 17–28
17.2.3.2. Read Procedure Call (S$ARREAD)...................... 17–29
17.2.3.3. Close-Input Procedure Call (S$ARCLOSI)........... 17–30
17.2.4. Status Lists for MASM READ Procedures .................. 17–30
17.3. Supported Character Set Types for the READ Function ...... 17–33
17.3.1. Fieldata ........................................................................ 17–33
17.3.2. ASCII/ISO and ASCII-like ............................................. 17–33
17.3.3. ASCII/ISO with Embedded Shift-Coded Kanji.............. 17–34
17.3.4. Attributed Character Data............................................ 17–34
Section 18. SAR$ WRITE.....................................................................18–1
18.1. WRITE Function/PLUS Interface ............................................ 18–1
18.1.1. WRITE Packet Data Structure Description .................... 18–1
18.1.1.1. Required Information for WRITE
Procedures........................................................ 18–2
18.1.1.2. Optional Information for WRITE Procedures ........ 18–4
18.1.1.3. Information Returned by WRITE
Procedures........................................................ 18–9
18.1.2. Buffers and Tables for PLUS WRITE Procedures........ 18–10
18.1.3. WRITE Procedures Called from PLUS......................... 18–12
18.1.3.1. SAR_OPEN_OUTPUT Procedure Call ................. 18–13
18.1.3.2. SAR_WRITE Procedure Call................................ 18–14
18.1.3.3. SAR_WRITE_CONTROL Procedure Call............. 18–15
18.1.3.4. SAR_CLOSE_OUTPUT Procedure Call ............... 18–17
18.1.3.5. Example .............................................................. 18–18
18.1.4. Status Lists for PLUS WRITE Procedures................... 18–19
18.2. WRITE Function/MASM Interface........................................ 18–21
18.2.1. WRITE Packet and Data Area Description................... 18–22
18.2.1.1. Required Information for WRITE
Procedures...................................................... 18–22
18.2.1.2. Optional Information for WRITE Procedures ...... 18–23
18.2.1.3. Information Returned by WRITE
Procedures...................................................... 18–27
18.2.1.4. WRITE Packet Definition PROC.......................... 18–28
18.2.2. MASM WRITE Procedures Buffers and Tables........... 18–29
18.2.3. WRITE Procedures Called from MASM ...................... 18–29
18.2.3.1. Open-Output Procedure Call (S$AROPENO)...... 18–29
18.2.3.2. WRITE Procedure Call (S$ARWRITE) ................. 18–30
18.2.3.3. Close-Output Procedure Call (S$ARCLOSO) ...... 18–31
18.2.4. Status Lists for MASM WRITE Procedures ................ 18–32
18.3. WRITE Function Supported Character Set Types ................ 18–34
18.3.1. ASCII/ISO and ASCII-like ............................................. 18–35
18.3.2. ASCII/ISO with Embedded Shift-Coded Kanji.............. 18–35
18.3.3. Attributed Character Data............................................ 18–35
7833 1733–004 vii

Contents
Section 19. SAR$ ATREAD ................................................................ 19–1
19.1. ATREAD Function/PLUS Interface......................................... 19–1
19.1.1. ATREAD Packet Data Structure Description................. 19–1
19.1.1.1. Required Information for ATREAD
Procedures ....................................................... 19–2
19.1.1.2. Optional Information for ATREAD
Procedures ....................................................... 19–3
19.1.1.3. Information Returned by ATREAD
Procedures ....................................................... 19–5
19.1.2. PLUS ATREAD Procedures Buffers and Tables............ 19–7
19.1.3. ATREAD Procedures Called from PLUS........................ 19–8
19.1.3.1. SAR_INITIALIZE_ATREAD Procedure Call ........... 19–8
19.1.3.2. SAR_ATREAD Procedure Call............................... 19–9
19.1.4. SAR_RESTORE_ATREAD Procedure Call ................... 19–11
19.1.5. Status Lists for PLUS ATREAD Procedures................ 19–11
19.2. ATREAD Function/MASM Interface .................................... 19–13
19.2.1. ATREAD Packet and Data Area Description................ 19–13
19.2.1.1. Required Information for ATREAD
Procedures ..................................................... 19–13
19.2.1.2. Optional Information for ATREAD
Procedures ..................................................... 19–14
19.2.1.3. Information Returned by ATREAD
Procedures ..................................................... 19–16
19.2.1.4. ATREAD Packet Definition PROC
(S$ARATRDEF)............................................... 19–17
19.2.1.5. ATREAD Packet Generation PROC
(S$ARATRPKT) ............................................... 19–18
19.2.2. MASM ATREAD Procedures Buffers and Tables ....... 19–19
19.2.3. ATREAD Procedures Called from MASM ................... 19–19
19.2.3.1. Initialize ATREAD Procedure Call
(S$ARINITATR) ............................................... 19–19
19.2.3.2. ATREAD Procedure Call (S$ARATREAD) ........... 19–20
19.2.3.3. Reset ATREAD Procedure Call
(S$ARRSATR) ................................................. 19–22
19.2.4. Status Lists for MASM ATREAD Procedures ............. 19–23
Section 20. SAR$ COM ...................................................................... 20–1
20.1. SAR$ COM Function/PLUS Interface .................................... 20–1
20.1.1. SAR$ COM Packet Data Structure Description ............ 20–1
20.1.1.1. Required Information for SAR$ COM
Procedure ......................................................... 20–1
20.1.1.2. Optional Information for SAR$ COM
Procedure ......................................................... 20–2
20.1.1.3. Information Returned by SAR$ COM
Procedure ......................................................... 20–6
20.1.2. SAR$ PLUS COM Procedure Buffers and Tables ......... 20–7
20.1.3. SAR$ COM Procedure Called from PLUS..................... 20–8
20.1.4. Status Lists for PLUS COM Procedure ......................... 20–9
20.2. SAR$ COM Function/MASM Interface................................ 20–11
viii 7833 1733–004

Contents
20.2.1. SAR$ COM Packet and Data Area Description ........... 20–11
20.2.1.1. Required Information for SAR$ COM
Procedure ....................................................... 20–11
20.2.1.2. Optional Information for SAR$ COM
Procedure ....................................................... 20–12
20.2.1.3. Information Returned by COM Procedure.......... 20–14
20.2.1.4. COM Packet Definition PROC
(S$ARCOMDEF) ............................................. 20–15
20.2.1.5. SAR$ COM Packet Generation PROC
(S$ARCOMPKT).............................................. 20–16
20.2.2. MASM SAR$ COM Procedure Buffers and
Tables ...................................................................... 20–17
20.2.3. SAR$ MASM COM Procedure Call (S$ARCOM)......... 20–17
20.2.4. Status Lists for the MASM COM Procedure............... 20–19
Section 21. SDFI, SDFO–System Data Format I/O Routines ................21–1
21.1. SDFI–System Data Format Input Routine .............................. 21–2
21.1.1. Packet............................................................................ 21–2
21.1.1.1. Packet Format....................................................... 21–3
21.1.1.2. Packet Generation PROC...................................... 21–4
21.1.2. Calling Sequence ........................................................... 21–7
21.1.2.1. Open SDFI ............................................................ 21–7
21.1.2.2. Read an Image ...................................................... 21–8
21.1.2.3. Close SDFI .......................................................... 21–10
21.2. SDFO–System Data Format Output Routine ....................... 21–10
21.2.1. Packet.......................................................................... 21–10
21.2.1.1. Packet Format..................................................... 21–11
21.2.1.2. Packet Generation PROC.................................... 21–13
21.2.2. Calling Sequence ......................................................... 21–16
21.2.2.1. Open SDFO......................................................... 21–16
21.2.2.2. Write an Image ................................................... 21–17
21.2.2.3. Close SDFO ........................................................ 21–17
21.3. Error Return.......................................................................... 21–18
Section 22. SFDT$–System Standard Format Date and Time .............22–1
22.1. MASM Interface..................................................................... 22–3
22.1.1. Packet............................................................................ 22–3
22.1.2. Calling Sequence ........................................................... 22–5
22.1.3. Example ......................................................................... 22–7
22.2. PLUS Interface ....................................................................... 22–8
22.2.1. Packet............................................................................ 22–8
22.2.2. Calling Sequence ......................................................... 22–11
22.2.3. Example ....................................................................... 22–12
22.3. SFDTBL$–Month and Day Table .......................................... 22–12
7833 1733–004 ix

Contents
Section 23. SIR$–Symbolic Input/Output Routine.............................. 23–1
23.1. SIR$–Control Options ............................................................ 23–6
23.2. SIR$ Entry Points ................................................................. 23–10
23.2.1. OPNSR$–Open SIR$ Input and Output....................... 23–10
23.2.2. INISR$–Initialize SIR$ Input and Output...................... 23–11
23.2.3. GETAS$–Get Symbolic Image in ASCII....................... 23–13
23.2.4. GETSR$–Get Symbolic Image in Fieldata ................... 23–16
23.2.5. GETNM$–Get Symbolic Image Without
Translation............................................................... 23–18
23.2.6. CLOSR$–Close SIR$ Input and Output....................... 23–19
23.3. External Labels..................................................................... 23–20
23.4. SIR$–Multipass Capability.................................................... 23–20
23.5. Compressed Symbolic Elements......................................... 23–20
Section 24. Program Trace Routine ................................................... 24–1
24.1. Calling Sequence ................................................................... 24–3
24.2. Terminating Trace .................................................................. 24–3
24.3. Symbol Tables........................................................................ 24–4
24.4. Demand Mode Operation ...................................................... 24–5
24.4.1. Contingency Processing................................................ 24–7
24.4.2. Demand Mode Commands........................................... 24–8
24.5. Control Flags ........................................................................ 24–18
Section 25. SOR–Symbolic Output Routine ....................................... 25–1
25.1. SSOR$–Start Symbolic Output .............................................. 25–2
25.2. SORASC$ and SORASCA$–Output ASCII Image.................. 25–3
25.3. Output Fieldata Image ........................................................... 25–4
25.4. SORNM$ and SORNMA$–Output Specified Coded
Character Set Image.......................................................... 25–5
25.5. ESOR$–End Symbolic Output................................................ 25–6
25.6. SOR File Control Table (SORFCT$)........................................ 25–6
Appendix A. Using SYSLIB ....................................................................A–1
A.1. Efficient Collections .................................................................A–1
A.2. PLUS Routines.........................................................................A–1
A.3. Compilations ............................................................................A–1
Appendix B. Diagnostic Messages ........................................................ B–1
B.1. Processor Interface Routine Messages...................................B–1
B.2. SIR$–Line-Change Diagnostics................................................B–4
x 7833 1733–004

Contents
Appendix C. SYSLIB Restrictions .......................................................... C–1
C.1. ASM Compatibility....................................................................C–1
C.2. Object Modules........................................................................C–1
C.3. SDFI and SDFO Tape Handling ................................................C–1
C.4. Symbolic Access Routine (SAR$).............................................C–1
C.5. 65K Addressing Limit ...............................................................C–1
Appendix D. SYSLIB Elements .............................................................. D–1
Appendix E. SYSLIB Common Bank Entry Points ..................................E–1
Appendix F. Interface to Selected Extended Mode Executive
Requests ............................................................................F–1
F.1. Calling Sequence...................................................................... F–1
F.2. Packet Generation .................................................................... F–2
F.2.1. EM$READPKT ................................................................. F–2
F.2.2. EM$PRINTPKT................................................................. F–3
F.2.3. EM$TREADPKT ............................................................... F–4
F.2.4. EM$SNAPPKT ................................................................. F–5
F.3. Example.................................................................................... F–6
Appendix G. INFOR Information ............................................................ G–1
G.1. INFOR Identifiers for Processor Call Statement ..................... G–1
G.2. The INFOR Table ..................................................................... G–3
G.3. INFOR Table Conventions....................................................... G–7
G.4. INFOR Table Example ............................................................. G–8
G.5. Reading the INFOR Table........................................................ G–9
G.6. Determining the INFOR Table Size ......................................... G–9
Appendix H. ASCII-like Character Sets ................................................. H–1
Appendix I. Extended Mode Interface to SYSLIB .................................. I–1
I.1. General ...................................................................................... I–1
I.2. Interface to the AEDIT$ Package .............................................. I–2
I.3. Interface to BSP$ ...................................................................... I–5
I.4. Interface to FDASC$ ................................................................. I–9
I.5. Interface to GETPSF$.............................................................. I–10
I.6. Interface to ID$ ....................................................................... I–12
I.7. Interface to INFOR$ ................................................................ I–13
I.8. Interface to MFDSP$............................................................... I–15
7833 1733–004 xi

Contents
Appendix J. Obsolete Entry Points, PROCs, and Routines.....................J–1
J.1. AEDIT$–Generating the AEDIT$ Packet .................................. J–1
J.1.1. A$EPKT ........................................................................... J–1
J.1.2. A$EPKTF ......................................................................... J–1
J.1.3. A$EPKTSFDT................................................................... J–2
J.1.4. Examples of Generating the AEDIT$ Packet................... J–2
J.2. CONWRD$–MASM PROCs and Entry Points ......................... J–2
J.3. EOUT$–Generalized Output Editing Routine ........................... J–3
J.3.1. Editing Functions............................................................. J–5
J.3.2. Output Functions............................................................. J–6
J.3.3. Modal Functions.............................................................. J–7
J.3.4. Control Functions ............................................................ J–8
J.3.5. EOUT$–Calling Sequences ............................................. J–9
J.4. I$D–Calling Sequence ............................................................ J–11
J.5. IDLINE$ and IDONLY$–Identification Line
Routines............................................................................. J–13
J.5.1. IDLINE$ ......................................................................... J–14
J.5.1.1. IDLINE$ ................................................................ J–14
J.5.1.2. IDTIME$................................................................ J–15
J.5.2. IDONLY$ ....................................................................... J–15
J.5.2.1. IDONLY$............................................................... J–15
J.5.2.2. IDTOME$.............................................................. J–15
J.6. SFDT$–MASM Calling Sequence .......................................... J–15
J.7. SYS$RLIB$ID–RLIB Identification.......................................... J–16
J.8. PIRCB$ Common Bank Entry Points ..................................... J–17
Appendix K. Related Product Information............................................. K–1
Glossary ..............................................................................................1
Index ..............................................................................................1
xii 7833 1733–004

Figures
4–1. AEDIT$: Packet Format ...................................................................................... 4–3
5–1. BSP$: File Control Table (FCT) .......................................................................... 5–5
8–1. EDIT$: Packet Format ....................................................................................... 8–2
12–1. INFOR$: Format of the ELT$ Table.................................................................. 12–9
14–1. PARTBL Table Format ...................................................................................... 14–4
15–1. ROR: Item Format ............................................................................................ 15–3
16–1. SAR$: Attribute Table Entry ........................................................................... 16–12
17–1. SAR$: Attribute Table Entry ........................................................................... 17–11
18–1. SAR$: Attribute Table Entry ........................................................................... 18–11
21–1. SDFI: Packet Format ....................................................................................... 21–3
21–2. SDFO: Packet Format..................................................................................... 21–11
22–1. SFDT$: Packet Format ..................................................................................... 22–3
7833 1733–004 xiii

Figures
xiv 7833 1733–004

Tables
2–1. MAXR$: Control Register and Partial Word Designator Mnemonics................. 2–3
2–2. SSTYP$: Element Subtypes .............................................................................. 2–5
2–3. ASUBTYP$: Absolute Element Subtypes and Sub-subtypes............................ 2–7
2–4. SYS$DEF: System Standard Definitions ........................................................... 2–8
4–1. AEDIT$: Initialization and Termination Editing Routines ................................... 4–9
4–2. AEDIT$: General Purpose ASCII Editing Routines .......................................... 4–10
4–3. AEDIT$F: Floating-Point ASCII Editing Routines ............................................. 4–16
4–4. AEDIT$T: ASCII Time and Date Editing Routines ........................................... 4–18
4–5. AEDIT$: Error Status Codes............................................................................ 4–24
8–1. Initialization and Termination.............................................................................. 8–5
8–2. General-Purpose Editing Routines ..................................................................... 8–6
8–3. Time and Date Editing Routines......................................................................... 8–8
8–4. EDIT$F–Floating-Point Editing Routines........................................................... 8–10
12–1. INFOR$: RINF$ Error Messages ..................................................................... 12–5
16–1. SAR$: Attribute Types and Values ................................................................ 16–13
17–1. SAR$: PLUS READ Buffer and Table Length Defaults ................................. 17–12
17–2. SAR$: PLUS READ Buffer and Table Type Definitions ................................. 17–12
17–3. SAR$: READ Procedure CALL_STATUS Codes ............................................ 17–17
17–4. SAR$: READ Procedure IO_STATUS Status List .......................................... 17–19
17–5. SAR$: MASM READ Buffer and Table Lengths............................................ 17–27
17–6. SAR$: READ Procedure SR$CALLST Status Codes ..................................... 17–30
17–7. SAR$: READ Procedure SR$IOSTAT Status Codes...................................... 17–32
18–1. SAR$: PLUS WRITE Buffer and Table Length Defaults................................ 18–12
18–2. SAR$: PLUS WRITE Buffer and Table Type Definitions ............................... 18–12
18–3. SAR$: WRITE Procedure CALL_STATUS Codes .......................................... 18–19
18–4. SAR$: WRITE Procedure IO_STATUS Status List......................................... 18–21
18–5. SAR$: MASM WRITE Buffer and Table Lengths .......................................... 18–29
18–6. SAR$: WRITE Procedure SW$CALLST Codes.............................................. 18–32
18–7. SAR$: WRITE Procedure SW$IOSTAT Status List ....................................... 18–34
19–1. SAR$: PLUS ATREAD Buffer and Table Length Defaults ............................... 19–7
19–2. SAR$: PLUS ATREAD Buffer and Table Type Definitions............................... 19–7
19–3. SAR$: ATREAD Procedure CALL_STATUS Codes........................................ 19–11
19–4. SAR$: ATREAD Procedure IO_STATUS Status List...................................... 19–13
19–5. SAR$: MASM ATREAD Buffer and Table Lengths ....................................... 19–19
19–6. SAR$: ATREAD Procedure SA$CALLST Status Codes................................. 19–23
19–7. SAR$: ATREAD Procedure SA$IOSTAT Status Codes ................................. 19–24
7833 1733–004 xv

Tables
20–1. SAR$: PLUS COM Buffer and Table Length Defaults .................................... 20–7
20–2. SAR$: PLUS COM Buffer and Table Type Definitions.................................... 20–7
20–3. SAR$: COM Procedure CALL_STATUS Codes............................................... 20–9
20–4. SAR$: MASM COM Buffer and Table Lengths ............................................ 20–17
20–5. SAR$: COM Procedure SC$CALLST Status Codes...................................... 20–19
B–1. SIR$: Line-change Diagnostics .........................................................................B–5
D–1. SYSLIB Elements ...............................................................................................D–1
D–2. SYSLIB Common Bank Absolute Elements.......................................................D–5
E–1. SYSLIB$1 Entry Points....................................................................................... E–1
E–2. SYSLIB$2 Entry Points....................................................................................... E–4
E–3. SYSLIB$3 Entry Points....................................................................................... E–5
E–4. SYSLIB$4 Entry Points....................................................................................... E–5
H–1. Character Set Types...........................................................................................H–1
I–1. EM$EDIT Function Codes................................................................................... I–3
I–2. EM$EDIT First Parameter Field Values............................................................... I–4
I–3. EM$EDIT Second Parameter Field Values.......................................................... I–4
I–4. EM$BSP Function Codes.................................................................................... I–7
I–5. EM$BSP Parameter Field Values........................................................................ I–7
I–6. EM$INFOR Function Codes.............................................................................. I–13
I–7. EM$INFOR Additional Parameter Field Values................................................. I–14
I–8. EM$MFDSP Function Codes ............................................................................ I–16
I–9. EM$MFDSP Parameter Field Values ................................................................ I–16
J–1. IDLINE$, IDONLY$: IDBUFF Length............................................................... J–14
J–2. PIRCB$ Entry Points ........................................................................................ J–17
xvi 7833 1733–004

Section 1
Introduction
1.1. About This Manual
This manual is a detailed programming reference for the OS 2200 System Service
Routines Library (SYSLIB). The descriptions of the SYSLIB routines include their calling
sequence, parameters, and error or normal returns.
Master Doc PLE
This manual contains all the information that was available at the time of publication.
Technical changes that were not available at the time of publication are documented in
problem list entry (PLE) 17668757. To obtain a copy of this PLE, log on with entitled
privileges to the Unisys Product Support web site (http://www.support.unisys.com/) or
contact your Unisys representative.
Audience
This manual is for developers of both application and system software in the OS 2200
environment. This standardized implementation of commonly required services
eliminates the need for detailed knowledge of internal OS 2200 data structures, which
are subject to change.
Prerequisites
To use the Service Library routines effectively, the programmer should be familiar with
• OS 2200 concepts, facilities, and job control language
• Executive system (Exec) concepts and facilities
• MASM and PLUS programming languages
7833 1733–004 1–1

Introduction
1.2. Notation Conventions
In this manual, the 36 bits of the computer word are numbered from left to right. For
example:
0 8 9 17 18 26 27 35
The following mnemonics define partial-word references:
sixth- S1 S2 S3 S4 S5 S6
word 0 5 6 11 12 17 18 23 24 29 30 35
quarter- Q1 Q2 Q3 Q4
word 0 8 9 17 18 26 27 35
third- T1 T2 T3
word 0 11 12 23 24 35
half- H1 H2
word 0 17 18 35
The 2200 Series Assembler mnemonics are used whenever machine instructions are
discussed. The Assembler mnemonics for partial-word transfers and registers are
defined in the MASM definition element MAXR$. These mnemonics are used in
assembly language programs.
The mnemonics U and XU indicate immediate data references. (The operand is taken
directly from the address portion of the instruction rather than from the main storage
referenced by that address.) The mnemonics XH1, XH2, and XU indicate that the system
will load the 18-bit value with sign extension to 36 bits (in other words, if bit 18 is a one,
bits 0 through 17 are set to one). This does not affect the store operation.
Control registers are referenced with the following mnemonics:
A0, A1,..., A15
Accumulators (A0 through A3 can also be used as index registers.)
A15+1, A15+2
Additional accumulators for double- or triple-precision instructions
1–2 7833 1733–004

X1, X2,..., X11
Index registers
R1, R2,..., R15
R registers
Activities may use one of two control register sets.
Major set
All control registers as described above
Minor set
Registers X8 through X11; A0 through A5; R1, R2, and R3
Introduction
Subroutines frequently use a subset of the minor set, called volatile registers. This
subset includes
Volatile set
Registers X11, A0 through A5, R1, R2, and R3
The volatile register set is assumed to be available for all routines in SYSLIB. The
AEDIT$/EDIT$ routines also use registers X1, X2, and X3, which are saved and restored.
When a subroutine uses one of the volatile registers, the register is not saved or
replaced. Any registers that are used but are not part of the volatile register set are
saved and restored.
The AEDIT$/EDIT$ routines assume that a subset of the volatile register set is available.
These registers are: A0, A1, A2, A3, R1, and X11, and they are not saved or restored.
The dollar sign ($) is generally used in system-defined external symbols, procedure
names, and file names; to avoid duplication, do not use this character. The $ generally
occurs as the last character of a symbol; an exception is procedure names in which the $
is usually the second character.
In calling sequences and table formats, parameters in italic type indicate information that
the calling program supplies; parameters in regular type indicate information that the
system returns.
Brackets indicate optional parameters. (The brackets are not part of the parameter and
are not included by the calling program.)
The symbol ∆ indicates a blank character.
In control statements, Executive requests, and procedure call formats, capital letters
indicate code that should be used as shown. Lowercase letters represent variables that
should be used as the text directs.
7833 1733–004 1–3

Introduction
Numbers are represented as in Assembler syntax; that is, a leading zero specifies octal.
Control statements have the following general format:
@label:command,options parameters . comments
or
@@command,options parameters . comments
Parameters are separated by commas. A field may specify a single parameter, or it may
contain several related parameters in subfields. Slashes (///) separate subfields. An
ellipsis (...) indicates that there may be any number of additional parameters following
the format of the last shown (for example, reel numbers of a tape file or elements to be
listed).
See the ECL and FURPUR Reference Manual for a complete discussion of control
statement syntax.
1.3. About SYSLIB
SYSLIB contains absolute, object module, omnibus, procedure, relocatable, and symbolic
elements.
The SYSLIB routines can be grouped into six functional areas. The following groupings
are only a subset of the SYSLIB elements. For a complete listing of all SYSLIB
elements, see Appendix D.
• System Procedures, Definitions, and Entry Points
AXR$ SYS$DEF
MAXR$ SSTYP$
PROC$ TABLE$
SDFP$ SYSLIB$ID
• Collector Interface Routines
DLOAD$ IDLAD$
IDL$ IDLD$
IDLA$ SNAP$
• Diagnostic and Debugging Routines
CABSAD$ CRELAD$
CONWRD$ SNOOPY
1–4 7833 1733–004

• Editing Routines
AEDIT$ SFDT$DG
AEDIT$F SFDTBL$
AEDIT$SFDT EDIT$
AEDIT$T EDIT$F
SFDT$ EDIT$T
SFDT$D
• Processor Interface Routines (PIRs)
BSP$ PREPRM
GETPSF$ PREPRO
ID$ ROR
INFOR$ SAR$
POSTPR$ SIR$
PREPF$ SOR
• Utility Routines
FDASC$ SDFI
MFDSP$ SDFO
Introduction
The Collector Programming Reference Manual explains the Collector interface routines.
This manual describes the remaining routines.
The method you use to install the SYSLIB routines determines which file or files will
contain the routines. If you install SYSLIB without COMUS, then the routines are placed
in two files, SYS$*RLIB$ and SYS$*LIB$. If you install with COMUS, all of the routines
are placed in the SYS$LIB$*SYSLIB file. The following paragraphs explain these two
arrangements.
If you install SYSLIB without COMUS, the SYSLIB routines are contained in the system
relocatable library file SYS$*RLIB$ along with other relocatable libraries. When a
program calls a SYSLIB routine, the Collector automatically searches SYS$*RLIB$ for the
routine and places the routine in the absolute program that the Collector is constructing.
Subsets of the SYSLIB routines are also contained in common banks. These common
banks reside in the system absolute library file SYS$*LIB$. The routines in the common
banks are the AEDIT$ package (AEDIT$, AEDIT$F, AEDIT$SFDT), BSP$, CABSAD$ and
CRELAD$, CONWRD$, FDASC$ (and TABLE$), GETPSF$, ID$, INFOR$, MFDSP$,
SAR$, SDFI, SDFO, and SFDT$ (and SFDTBL$). See Section 3 for details of how to
access the routines in the SYSLIB common banks.
7833 1733–004 1–5

Introduction
If you install SYSLIB using COMUS (level 4R2 and higher), all of the routines and the
common banks are placed in the SYSLIB product file SYS$LIB$*SYSLIB. The Collector
(level 31R2 and higher) automatically searches SYS$LIB$*SYSLIB for referenced SYSLIB
routines and places them in the absolute program that it is constructing. MASM (level
4R2 and higher) also automatically searches SYS$LIB$*SYSLIB.
Several restrictions apply to the released level of SYSLIB. For details of these
restrictions, see Appendix C.
1–6 7833 1733–004

Section 2
System Standard Procedures and
Definitions
This section describes system definitions and procedures that are provided by SYSLIB.
System definitions are supplied to calling programs for information such as
• Mnemonics for control registers
• Names and bank descriptor indexes (BDI) for some system configured common
banks and entry points to the common banks
• Program file element subtype mnemonics and codes
SYSLIB procedures perform functions such as
• Generating calling sequences to SYSLIB routines
• Generating ASCII and Fieldata character sets
• Defining ASCII control characters
2.1. Common Bank Entry Points
System configured common bank names, their associated BDI values, and the absolute
values of the entry points to the common banks are defined in relocatable elements with
CBEP$$ as the first six characters of the element name. This element naming
convention is used by the Collector to detect the use of configured common banks.
During program collection, the Collector automatically includes CBEP$$ elements that
contain configured common bank names or entry points referenced in the program being
collected.
7833 1733–004 2–1

System Standard Procedures and Definitions
The relocatable element CERU$ is located in the EXEC system relocatable library file,
SYS$*RLIB$. CERU$ reserves 620 BDI values for users. The BDI values reserved for
users are
0400300 to 0400323
0400400 to 0400411
0400500 to 0400511
0400600 to 0400611
0400700 to 0400711
0401000 to 0401011
0401100 to 0401111
0401200 to 0401211
. . .
. . .
0403300 to 0403311
. . .
. . .
0407700 to 0407711
2.2. MAXR$–Register and Partial-Word Definitions
MAXR$ is a MASM definition mode (omnibus) element that defines mnemonic
designators for
• Control registers
• Base registers
• J-registers and staging registers
• Partial-word designators
For a complete description of these registers, refer to the applicable processor and
storage reference or the AIM Programming Reference Manual.
Table 2–1 lists the mnemonic designators and absolute addresses of control registers
and partial-word designators that MAXR$ contains.
All registers used in assembler programs must be defined. The following example
shows how to include MAXR$ in assembly language source code. MAXR$ defines the
register (A0) and J-designator (U).
$(1),START
$INCLUDE 'MAXR$'
L,U A0,1
ER EXIT$
$END START
2–2 7833 1733–004

System Standard Procedures and Definitions
The MASM PROC AXR$ also defines these mnemonic designators.
Table 2–1. MAXR$: Control Register and Partial Word Designator Mnemonics
Base Registers
Index
Registers
Arithmetic
Registers
R-Registers
Staging
Registers and
J-Registers
Partial-Word
Designators
Mne Val Mne Abs Mne Abs Mne Abs Mne Abs Mn-J J-Va
B0 0 X0 0 A0 14 R0 100 SR1 103 W (or
none)
B1 1 X1 1 A1 15 R1 101 SR2 104 H1 1
B2 2 X2 2 A2 16 R2 102 SR3 105 H2 2
B3 3 X3 3 A3 17 R3 103 J0 106 XH2 3
B4 4 X4 4 A4 20 R4 104 J1 107 XH1 4
B5 5 X5 5 A5 21 R5 105 J2 110 T3 5
B6 6 X6 6 A6 22 R6 106 J3 111 T2 6
B7 7 X7 7 A7 23 R7 107 T1 7
B8 10 X8 10 A8 24 R8 110 S1 15
B9 11 X9 11 A9 25 R9 111 S2 14
B10 12 X10 12 A10 26 R10 112 S3 13
B11 13 X11 13 A11 27 R11 113 S4 12
B12 14 A12 30 R12 114 S5 11
B13 15 A13 31 R13 115 S6 10
B14 16 A14 32 R14 116 Q1 7
B15 17 A15 33 R15 117 Q2 4
Legend
Mne Mnemonic
Val Value (octal)
Abs Absolute (octal)
Mn-J Mnemonic for J
J-Val J-Value (octal)
7833 1733–004 2–3
0

System Standard Procedures and Definitions
2.3. PROC$–System Procedures
PROC$ is an element that contains the following assembler procedures (PROC). Refer
to the designated section of this manual or to the other manuals listed below for
instructions on how to use these procedures. Only those PROCs that are not described
elsewhere in this document are listed.
• Collector segment loading PROCs. See the Collector Programming Reference
Manual. (L$OAD, D$REL, D$LOAD)
• Procedures that generate calls to the PMD dynamic dump routines (X$MARK,
X$BACK, X$BUFR, X$SIZE, X$IF, X$OR, X$AND, X$LST, X$TALY, X$FRMT,
X$MESG, X$CREG, X$DUMP, X$CORE, X$DRUM, X$TAPE, X$FILE, X$CW, X$ON,
X$OFF). See the PMD Programming Reference Manual.
• Procedures, ASCII and FIELDATA, used with the Meta-Assembler (MASM) to
change the radix for generating character data.
• Procedure A$SCTRL to define mnemonics for the ASCII control characters
corresponding to octal codes 0 through 37 and 177. See the ER Programming
Quick-Reference Guide.
• J$REG PROC to aid loading J-registers in character addressing mode. See the AIM
Programming Reference Manual.
• I$BJ and D$BJ PROC calls to generate IBJ$ (DBJ$) calling sequences used by the
Collector in bank switching. See the Collector Programming Reference Manual.
• U$C function to uppercase ASCII character string. For example
P$ $PROC
U$C
TYPE $EQU U$C(P$(0,1) . Get type in uppercase ASCII
$IF TYPE='A'
...
$ENDF
$END
2.4. SSTYP$–Element Subtypes
SSTYP$ is a nonexecutable relocatable element consisting of a table of standard
symbolic and omnibus element subtype names and their associated values. It has a
single external definition, SSTYP$. SSTYP$ is the address of a word that contains the
length of the table. The table begins at SSTYP$ + 1.
The element subtype number is used to index into the SSTYP$ table to obtain the
corresponding Fieldata name. For example, the octal value for an element subtype of
'PLS' (PLUS) is 015. The word at address SSTYP$+16 contains the Fieldata characters
'PLS∆∆∆'.
2–4 7833 1733–004

System Standard Procedures and Definitions
If the element subtype number exceeds the length of SSTYP$, no table entry exists.
The released table length is 64 words. If the element subtype number does not have a
definition, SSTYP$ contains the number in Fieldata characters. For example, the octal
value 076 does not have a subtype definition assigned to it. The word at address
SSTYP$+077 contains the Fieldata characters '076∆∆∆'.
Entries in the SSTYP$ table are one to four Fieldata characters per word, left-justified and
space-filled.
The element subtype codes are stored in the element table items in the program file
table of contents. See 5.1.7 regarding packet formats for table item add.
Table 2–2 contains the currently defined symbolic and omnibus element subtypes.
Table 2–2. SSTYP$: Element Subtypes
Mnemonic Code Description
SYM 00 Symbolic (No subtype)
ELT 01 ELT
ASM 02 Assembler
COB 03 COBOL
FOR 04 FORTRAN
ALG 05 ALGOL
MAP 06 Collector
DOC 07 Document processor
SEC 010 SECURE processor
SSG 011 Symbolic Stream Generator
APL 012 A Programming Language
BAS 013 BASIC
LSP 014 LISP
PLS 015 PLUS
PL1 016 PL/I
CTS 017 Conversational Time Sharing
FLT 020 FLIT processor
PNC 021 Panic
TCL 022 Traffic Control Language
MSM 023 Meta-Assembler (MASM)
MSD 024 MASM definition language
MAC 025 MACRO
APT 026 Automatically Programmed Tools
7833 1733–004 2–5

System Standard Procedures and Definitions
Table 2–2. SSTYP$: Element Subtypes
Mnemonic Code Description
PGA 027 PROMEGA
QLP 030 Query Language Processor
INL 031 PLUS INLINE processor
DCL 032 Declaration Control Language
SDL 033 System Definition Language
FDP 034 File Definition Processor
PSP 035 PLUS Procedure
PAS 036 PASCAL
IPF 037 Interactive Processing Facility
GSA 040 General Syntax Analyzer
MSG 041 Local language message system
(LLMS)
PRT 042 Symbionts
RPG 043 Report Program Generator
ADA 044 Ada language
PEER 045 Program Execution Evaluation Routine
C 046 C language
FHLL 047 FLIT High-Level Language
LINK 050 Linking System
COM 051 COMUS
PADS 052 Programmer's Advanced Debugging
System
SSDP 053 Subsystem Definition Processor
FLDP 054 Form Language Definition Processor
(DPS)
2–6 7833 1733–004

System Standard Procedures and Definitions
2.5. ASUBTYP$–Executable Element Subtypes and
Sub-subtypes
ASUBTYP$ is a nonexecutable relocatable element consisting of a table of executable
element subtype and sub-subtype mnemonics. An executable element can be one of
several subtypes and each subtype can have sub-subtypes associated with it.
For the absolute element subtype/sub-subtype table, a two-part access must be used.
Because each absolute subtype can have more than one associated sub-subtype, the
first access obtains a pointer to the subtype's sub-subtype mnemonic table. The second
access, using the sub-subtype value from the element table, will obtain the Fieldata
mnemonic for the absolute element.
The initial access is off of ASUBTYP$ + 1 as follows:
LA A0,ASUBTYP$+1,A0
Here, A0 is conditioned with the absolute element's subtype from word 7, bits 0–5 in the
element table entry. Next, with A1 conditioned with the element's sub-subtype value
from word 7, bits 6–11 in the element table entry:
AA,U A0,1,A1
Register A0 now points into the sub-subtype mnemonic table for the particular subtype,
then:
LA A1,0,A0
Register A1 contains the Fieldata mnemonic identifying the absolute element.
The Data Structures Programming Reference Manual contains details on the program file
element table entry for absolute elements.
Table 2–3 contains the currently defined absolute element subtypes and sub-subtypes.
Table 2–3. ASUBTYP$: Absolute Element Subtypes and
Sub-subtypes
Mnemonic Numeric Subtype Numeric Sub-subtype Description
ABS 0 0 Absolute
OM 1 0 Object Module
BOM 1 1 Bound Object Module
SSD 2 0 Subsystem Definition
ZOOM 3 1 Zero Overhead Object
Module
7833 1733–004 2–7

System Standard Procedures and Definitions
2.6. SYS$DEF–System Definitions
SYSLIB provides SYS$DEF as a relocatable, omnibus, and object module element that
equates externally defined mnemonic names to system definitions. These definitions
can be obtained during an assembly by including the following in the source code:
$INCLUDE 'SYS$DEF'. Table 2–4 contains the mnemonic names and values defined by
SYS$DEF.
Table 2–4. SYS$DEF: System Standard Definitions
Name Description
CYCLIM$ Symbolic element cycle maximum
EMPCTBD$ BDI value for Extended Mode user PCT bank
PCTBD$ BDI value for user PCT bank
PFET$ Starting sector address of the element table
PFAPT$ Starting sector address of the assembler procedure table
PFCPT$ Starting sector address of the COBOL procedure table
PFFPT$ Starting sector address of the FORTRAN/PLUS procedure table
PFEPT$ Starting sector address of the relocatable element entry point table
PFTEXT$ Starting sector address of the element text area
LPF$ET Starting sector address of the large program file element table
LPF$APT Starting sector address of the large program file assembler procedure
table
LPF$CPT Starting sector address of the large program file COBOL procedure
table
LPF$FPPT Starting sector address of the large program file FORTRAN/PLUS
procedure table
LPF$REEPT Starting sector address of the large program file relocatable element
entry point table
LPF$TEXT Starting sector address of the large program file element text area
RPCTA$ User entry point to PCT bank
PF$ID Program file identifier
LPF$ID Large program file identifier
LEPF$ID Large element program file identifier
PF$LEVEL0 Current revision level for the standard program file
LPF$LEVEL1 Current revision level for the large program file
LEPF$LEVEL1 Current revision level for the large element program file
ASCLIKE$ A 72-bit ASCII-like bit mask. Bit 71-n is set to 1 if coded character set
(CCS) n is defined as ASCII-like. Otherwise, the bit is 0. See
Table 1–1. This double-word equate is defined only for the omnibus
version of SYS$DEF.
2–8 7833 1733–004

System Standard Procedures and Definitions
2.7. SYSLIB$ID–SYSLIB Identification
SYSLIB$ID is a relocatable element in the SYSLIB installation file, SYS$LIB$*SYSLIB. It
is also included in each of the SYSLIB common banks. This element identifies the
SYSLIB level only. That is, it does not perform any functions. SYSLIB$ID defines the
following external labels:
SYSLIB$ID1 First 4 characters of ID in ASCII
SYSLIB$ID2 Second 4 characters of ID in ASCII
SYSLIB$ID3 Third 4 characters of ID in ASCII
For example, the definitions for SYSLIB 75R2Q7 are
SYSLIB$ID1 $EQU 75R2
SYSLIB$ID2 $EQU Q7∆∆
SYSLIB$ID3 $EQU ∆∆∆∆
7833 1733–004 2–9

System Standard Procedures and Definitions
2–10 7833 1733–004

Section 3
SYSLIB Access Methods
SYSLIB routines AEDIT$, AEDIT$F, AEDIT$SFDT, BSP$, CABSAD$, CRELAD$,
CONWRD$, FDASC$, GETPSF$, INFOR$, ID$, MFDSP$, SAR$, SDFI, SDFO, and SFDT$
are available as both relocatable and common bank routines. When using the common
bank version of these routines, the library routine is not collected into the calling
program.
The calling program contains a jump to the common bank that contains the library
routine, but the actual code of the library routine remains in the common bank. Because
the common bank code does not get collected into the calling program, as the
relocatable versions of the routines do, the calling program will be smaller. In cases
where the library routine is large, this can result in a considerable saving of space. Also,
since the common bank library routines exist independently of the calling programs, they
may be modified without forcing the calling programs to be recompiled or re-collected.
The jumps in the calling program remain valid even though the common bank code itself
changes. When transporting an absolute program from one machine to another, the
second machine must have the common bank library routines installed or the absolute
program may guard mode or produce unpredictable results.To check on whether the
SYSLIB common bank routines have been installed, it is only necessary to look for the
absolute elements SYSLIB$1, SYSLIB$2, SYSLIB$3, and SYSLIB$4 in the file that
contains the SYSLIB routines. These elements replace the SYSLIB common bank
PIRCB$. However, PIRCB$ is still included to enable programs that were collected
before the installation of SYSLIB level 75R3 to continue to run correctly.
If an installation of SYSLIB is done using COMUS level 4R2 (and higher levels), then the
SYSLIB common banks are put in the file SYS$LIB$*SYSLIB. If COMUS is not used for
the installation of SYSLIB, then the elements will be contained in the file SYS$*LIB$. All
the SYSLIB common banks have a starting address of 01000.
Table D–2 in Appendix D lists the highest address of all SYSLIB common banks. The
address of the SYSLIB level identifier is kept at 01003. The first word of the identifier is
the number of words in the identifier followed by the ASCII character representation of
the SYSLIB level (for example, 75R3).
Some of the common bank SYSLIB routines require the calling program to provide a data
area or a packet containing information that the routine needs. This area must be
contained within a bank that is write enabled and based when the SYSLIB routine is
called, and its addressing range must not overlap that of the SYSLIB common bank.
7833 1733–004 3–1

SYSLIB Access Methods
All the SYSLIB routines are available as relocatable elements. The routines listed at the
beginning of this section are also available as common bank routines. For the SYSLIB
routines CABSAD$, CONWRD$, CRELAD$, GETPSF$, ID$, INFOR$, MFDSP$, and
SFDT$, SYSLIB provides procedures that generate the calling sequence to access these
routines. These procedures have been provided for the convenience of the calling
program. Through the use of a parameter on the procedure call, they allow the calling
program to access the relocatable version of the SYSLIB routine, the common bank
version of the SYSLIB routine using the I$BJ calling sequence or the common bank
version of the SYSLIB routine using the Auto Switch calling method.
One of the advantages of using these procedures is that if a change to the calling
sequence of the routine has to be made, an internal change to the SYSLIB calling
procedure can also be made, and the calling program can remain the same. For the
SYSLIB routines that do not have a procedure provided to generate the calling sequence,
the calling program must explicitly code these instructions. The method for calling a
particular SYSLIB routine is contained in the chapter describing the routine. Some
general considerations on the different types of calls are given in the following
subsections.
3.1. Relocatable Collection Method
The Relocatable Collection method causes the SYSLIB relocatable element to be
collected into the calling program and become an integral part of it. Once this has been
done, the resulting absolute element will not be affected by any changes made to the
version of SYSLIB on the system. In other words, any SYSLIB routines the program
requires are retrieved from the system library file and collected along with the other
relocatable elements of the program to form an absolute element. If this type of call to
SYSLIB is used, the resulting absolute can be transported from one system to another
without regard as to what level of SYSLIB is on the other machine. Also, any changes
made to SYSLIB after the program has been collected have no effect on how the
program performs.
For the SYSLIB routines that have a procedure to generate the calling sequence, this is
the type of call that is generated as the default if the Common Bank call or Auto Switch
call are not requested.
3–2 7833 1733–004

3.2. Common Bank Call Using I$BJ
SYSLIB Access Methods
The I$BJ calling sequence is the preferred method of calling the SYSLIB common bank
routines. For the SYSLIB routines with a calling procedure, this is the type of call that is
generated when the calling program sets the parameter on the call to access the
common bank version of the routine. This method provides a much more flexible means
of using the SYSLIB routines than the Auto Switch method or explicitly coding an LIJ
instruction, and it retains all the advantages associated with using the common bank
version of the routines. That is, the calling program remains small because the SYSLIB
routines do not become an actual part of the calling program absolute. In addition, the
calling program will automatically reference new versions of the SYSLIB routines as they
are installed without the need for the calling program to be recompiled or re-collected.
Another advantage to using the I$BJ calling sequence is that the calling program can
switch between using the common bank version of the routines and the relocatable
version of the routines by re-collecting the program with the proper collector EQU
directives. A recompilation of the calling program is unnecessary; only a recollection is
needed. For example, if the following call to the MFDSP$ routine were in a program, the
common bank version of the MFDSP$ routine would be used.
M$FDSP,'CB' PKTLENGTH,PKTADDR,FUNCCODE
To force the program to use the relocatable version of the MFDSP$ routine, it would only
be necessary to re-collect the program with the following Collector directives included:
IN MFDSP$
EQU CBMFDSP$/MFDSP$
The Collector directive EQU forces the tag CBMFDSP$ to be evaluated as MFDSP$. An
explicit inclusion of the element that contains the entry point MFDSP$ (in this case the
element name is MFDSP$) is necessary to avoid errors during the collection. Appendix
E lists the names of all the common banks and relocatable entry points and the names of
the SYSLIB elements that include them. After the collection, the SYSLIB routine
MFDSP$ is an integral part of the new absolute program. This adds about 1,000 words
to the size of the absolute element.
Programs that originally call the relocatable version of a SYSLIB routine, for example
I$BJ X11,RFTI$ . BSP$, read file table index
and that wish to call the common bank version of the routine need the following
collector directives:
IN CBEP$$SYSLIB
EQU RFTI$/CBRFTI$
The Collector directive EQU forces the tag RFTI$ to be evaluated as CBRFTI$. The
explicit inclusion of the element CBEP$$SYSLIB is necessary to resolve the reference to
CBRFTI$. The element CBEP$$SYSLIB contains all the common bank entry point names
and must be explicitly included in collections that use the EQU directive to switch from
the relocatable version of a SYSLIB routine to the common bank version of the routine.
7833 1733–004 3–3

SYSLIB Access Methods
This type of switching between relocatable and common bank versions of a routine can
be done as long as the calling program makes use of the I$BJ instruction instead of an
LMJ or LIJ instruction to call the SYSLIB routines. For SYSLIB routines with a calling
procedure, the field that determines the type of call to make to the routine must be set
to 'CB' (common bank). If the field is set to 'A' (call the common bank version of the
routine using the Auto Switch calling sequence) or left blank (a blank field means call the
relocatable version of the routine), then the calling procedure generates an LMJ
instruction. If an LMJ instruction or an LIJ instruction is generated to call the routine,
then the program cannot switch between the common bank version and the relocatable
version as described above.
The I$BJ instruction is necessary because it remains undefined until the program is
collected. At collection time, the I$BJ is resolved to an LMJ if the label being referenced
resides in the same bank as the instruction referencing it, or it is resolved to an LIJ if the
label is in another bank. Programs written before the implementation of the I$BJ routine
may contain calling sequences such as the one that follows.
LXI,U X11,PIRCB$
LIJ X11,BASCFD$
This sequence requires the calling program to know which common bank contains the
routine as well as the name of the routine. Since the LIJ instruction is explicitly coded
into this program, it always calls the common bank version of the SYSLIB ASCII to
Fieldata routine. The program would have to be rewritten and reassembled to make it
reference the relocatable version of the SYSLIB routine. A more flexible calling
sequence is
I$BJ X11,CBFDASC$
The I$BJ procedure determines whether or not to generate a call to a common bank
based on the label included on the call, in this case. If a common bank call is generated,
the procedure handles retrieving the bank descriptor index of the common bank. Prior to
executing the above calling sequence, the calling program must ensure that the correct
values required by the SYSLIB routine have been loaded into the correct registers.
For more information on common bank calls and the I$BJ routine, consult the Collector
Programming Reference Manual.
3–4 7833 1733–004

SYSLIB Access Methods
3.3. Common Bank Call Using Auto Switch Method
The Auto Switch method of referencing the common bank version of the SYSLIB
routines requires the calling program to be explicitly aware of its own addressing
structure. The program must know what banks are based and the addressing range of
each bank. To access one of the SYSLIB routines, the calling program bases the
particular SYSLIB common bank that contains the routine. (See Appendix D and
Appendix E for the list of the SYSLIB common banks, the routines that are contained in
them, and the addressing limits of the bank.) The program then executes an LMJ
instruction to the common bank entry-point address minus 1. The calling program must
ensure that none of the banks it has based overlap the SYSLIB addressing space.
The advantage to this system is that the program may force the SYSLIB common bank
to remain based so that multiple calls to routines in that bank can avoid the expense of
basing the bank again and again. When the I$BJ method of accessing the common bank
routines is used, it unbases the active bank of the calling program, bases the SYSLIB
common bank, executes the SYSLIB routine, then unbases the SYSLIB common bank
and bases the calling program once again.
The disadvantage to the Auto Switch method is that the structure of the calling program
needs to be rigidly defined. Any changes to the program must always take into
consideration what banks are based at what times and the addressing range of the
banks. For these reasons, the use of the Auto Switch method is not encouraged. The
Auto Switch calling method can only be used on systems that can base more than one
bank simultaneously using the LIJ instruction.
For the SYSLIB routines that have procedures to generate the calling code, the Auto
Switch calling sequence is generated by appropriately setting a parameter on the
procedure call.
7833 1733–004 3–5

SYSLIB Access Methods
3–6 7833 1733–004

Section 4
AEDIT$–ASCII Image Composition
Editing Package
The AEDIT$ package is a set of ASCII editing subroutines. The calling program uses
these subroutines to compose strings of ASCII characters in a specified data area.
AEDIT$ is helpful in composing ASCII images for
• ASCII output printed by ER APRINT$, ER APRNTA$, and ER SYMB$ (PRINT$)
• ASCII output punched by ER APUNCH$, ER APNCHA$, and ER SYMB$ (PUNCH$)
• Other Executive requests that require ASCII images, such as ER ASCF$, ER CSI$,
and ER QECL$
• Any other applications that require ASCII images
AEDIT$ uses the full ASCII character set. Images are built up from individual characters
or groups of characters or by copying character strings from other data areas. AEDIT$
allows the calling program to use column settings when composing the ASCII image.
AEDIT$ edits numeric data into ASCII characters. This includes decimal, octal, and
floating-point numbers. The floating-point numbers can be either single-precision or
double-precision. AEDIT$ also creates an ASCII string containing the date and time,
using standard formats. AEDIT$ uses the current date and time, or a date and time
specified by the calling program.
AEDIT$ places the composed image in the data area or buffer provided by the calling
program.
AEDIT$ is reentrant and does not use any D-bank storage. The calling program supplies
the packet for AEDIT$, which is used to pass information to and from the AEDIT$
routines. The size of the AEDIT$ packet is 17 words. The packet format is described in
4.1.
AEDIT$ is available in both relocatable and common bank versions. The relocatable and
common bank entry points for the AEDIT$ routines are listed in Appendix E.
AEDIT$ establishes an "edit mode" while the image is being composed. The edit mode
begins when the A$EDIT or A$EDITR PROCs are called and terminates when the
A$EDITX or A$EPRINT PROCs are called. The AEDIT$ routines use the volatile register
set. In addition, the relocatable version of AEDIT$ saves the contents of and uses
registers X1, X2, and X3 during edit mode. These registers must not be modified during
edit mode. AEDIT$ restores the original contents when exiting edit mode.
7833 1733–004 4–1

AEDIT$–ASCII Image Composition Editing Package
The common bank version of AEDIT$ uses only register X1 during edit mode. If the
calling program modifies X1 during edit mode, it must reset H2 of X1 to the address of
the AEDIT$ packet.
The AEDIT$ editing package consists of five elements:
AEDIT$ General-purpose editing routines
AEDIT$F Floating-point editing routines
AEDIT$P Procedure calls for editing routines
AEDIT$SFDT System standard format date and time editing routines
AEDIT$T Date and time editing routines
AEDIT$ does not reference any other routines. AEDIT$T uses AEDIT$. AEDIT$SFDT
uses AEDIT$ and SFDT$.
The AEDIT$ routines expect input strings to be in the ASCII character set. The $ASCII
MASM directive can be used to insure all generated strings (strings between single
quotes) will be in the ASCII character set. Fieldata mode can be entered after the
AEDIT$ routines by using the $FDATA MASM directive. If strings are generated in an
area of the code that must remain in Fieldata mode, the $CAS (Convert to ASCII String)
function may be used to convert specific strings to ASCII.
4.1. Packet
The calling program must provide a packet for the AEDIT$ routines. The AEDIT$ packet
format and the procedure to generate the packet are described in the following
subsections.
4–2 7833 1733–004

4.1.1. Packet Format
AEDIT$–ASCII Image Composition Editing Package
The format of the AEDIT$ packet is shown in Figure 4–1. This packet format is provided
for information only; the AEDIT$ packet is generated by the MASM procedures
described in 4.1.2. The size of the AEDIT$ packet is 17 words. This packet is used for
all AEDIT$, AEDIT$F, AEDIT$T, and AEDIT$SFDT functions.
If A$EDITPKT is not called to generate the AEDIT$ packet, then the calling program must
supply the fields of the AEDIT$ packet indicated by italics. All other fields in the packet
are reserved for use by AEDIT$, and are not to be used by the calling program.
0 5 6 11 12 17 18 23 24 29 30 35
0 Test and
Set
1 character
index
qwm imagelength
relative word
index
2 fps fpr flag
bits
AEMSG$
character
index
image-address
AEMSG$ word index
zero return address for character store
(22-bit absolute address)
3 user's return address save of original X1 modifier
4 save of original X2 contents, or save of character pointer
5 save of original X3 contents, or save of word pointer
6 msg dpc spc ilx
7 reserved for future use
(must be zero)
digits before
decimal point
digits after
decimal
point
negative
sign
8 final column position exponent's power of 10
9 save area for intermediate floating-point results
10
not
normalized
11 Version date-format time-format error code zero separator
character
12 month
(TDATE$)
day
(TDATE$)
year
(TDATE$)
seconds since midnight (TDATE$)
13 time in milliseconds (TIME$) since midnight
14
15 used by common bank version
16
Figure 4–1. AEDIT$: Packet Format
7833 1733–004 4–3

AEDIT$–ASCII Image Composition Editing Package
4.1.2. Packet Generation PROC
The MASM PROC A$EDITPKT generates the AEDIT$ packet. The calling program
supplies the parameters in italics. The parameters in brackets are optional and may be
omitted. If they are omitted, the default value is used.
Calling Sequence
label A$EDITPKT image-length, image-address [‘MSG’,msg];
[‘FPS’, fps] [‘FPR’, fpr] [‘DPC’, dpc];
[‘SPC’, spc] [‘DFT’, date-format] [‘TFT’, time-format];
[‘SEP’, separator-character]
where:
label
The label that identifies the beginning of the AEDIT$ packet.
image-length
The word length of the data area that is to contain the image. The maximum length
is 63 words. If a larger data area is required, set this field to zero and the ilx field to
the word length, with a maximum length of 511 words.
image-address
msg
fps
fpr
The address of the data area where AEDIT$ constructs the image.
The stop character for the A$EMSG and A$EMSGR subroutines. The default is ‘&'.
The number of digits placed to the left of the decimal point for scientific format,
floating-point editing. The default is 1.
The flag for floating-point rounding.
0 Floating-point numbers are not rounded.
1 Floating-point numbers are rounded (default).
Example with fpr = 1:
Input 1.4356
3 digits printed
Result = 1.44
4–4 7833 1733–004

dpc
spc
AEDIT$–ASCII Image Composition Editing Package
The character that separates the mantissa and the exponent for scientific format,
double-precision, floating-point editing. The default is no character used.
The character that separates the mantissa and the exponent for scientific format,
single-precision, floating-point editing. The default is no character used.
date-format
The date format index (0 through 8), corresponding to the date formats listed in
4.2.4. If set to zero, the date is not formatted; only the time is formatted. The
default is 8.
time-format
The time format index (0 through 3), corresponding to the time formats listed in
4.2.4. If set to zero, the time is not formatted; only the date is formatted. The
default is 2.
separator-character
The character used to separate the date and time formats. It may be either a space
(default) or a dash.
Note: The A$EDITPKT proc sets the flag bits (word 2, bits 12 and 13) to 1 and the
version (word 11, bits 0:5) to 1.
4.1.3. Examples
The following examples generate the AEDIT$ packet from MASM programs.
Example 1
$(2)
PACKET A$EDITPKT 20,ASCIILINE . AEDIT$ packet
ASCIILINE $RES 20 . Data area for ASCII image
In example 1, the MASM procedure A$EDITPKT generates the AEDIT$ packet at the
location PACKET in location counter 2. AEDIT$ stores the generated ASCII string in the
20-word data area at location ASCIILINE. All other parameters are set to the default
values.
7833 1733–004 4–5

AEDIT$–ASCII Image Composition Editing Package
Example 2
LINELEN $EQU 33 . Length of ASCII data area
$(4)
LINE $RES LINELEN . Data area for ASCII image
PACKET A$EDITPK LINELEN,LINE ‘DFT’,2 ‘TFT’, 3 . AEDIT$ packet
In example 2, the MASM procedure A$EDITPKT generates the AEDIT$ packet for ASCII
editing with date and time formats. AEDIT$ stores the generated ASCII string in the 33word
data area at location LINE. AEDIT$ uses date format index 2 and time format
index 3. AEDIT$ uses the default values for the msg, fps, fpr, dpc, spc, and separatorcharacter
parameters.
Example 3
BUFLEN $EQU 8 . Length of buffer for f-p number
$(2)
FPNUM $RES BUFLEN . Buffer for floating-point number
FPPKT A$EDITP BUFLEN,FPNUM ‘FPR’,0 ‘DPC’,’D’ . AEDIT$ packet
In example 3, the MASM procedure A$EDITPKT generates the AEDIT$ packet at location
FPPKT. AEDIT$ stores the generated ASCII strings in the eight-word buffer at location
FPNUM. AEDIT$ does not round floating-point numbers and uses a separator character
of 'D'. AEDIT$ uses the default values for the msg, fps, spc, date-format, time-format,
and separator-character parameters.
4.2. Calling Sequence
There are several categories of AEDIT$ routines.
• General-purpose editing routines (see 4.2.1)
• Floating-point editing routines (see 4.2.2)
• Time and date editing routines (see 4.2.3)
• System standard format date and time editing routines (see 4.2.4)
The calling program calls the AEDIT$ routines with MASM PROCs from the element
AEDIT$P. Each routine has a corresponding PROC. The PROCs can call either the
relocatable or common bank version of AEDIT$. The relocatable version is called with an
LMJ on X11 to the relocatable entry point. The common bank version is called with an
IBJ$ on X11 to the common bank entry point or an LMJ on X11 to the common bank
entry point if the Auto Switch method is used.
4–6 7833 1733–004

The general calling format for the AEDIT$ PROCs is
A$Exxxxx [,t] p1,p2
where:
xxxxx
t
p1, p2
Characters for the specific AEDIT$ PROC call.
AEDIT$–ASCII Image Composition Editing Package
The type of call to AEDIT$. This parameter is optional and may be omitted. CB or A,
if specified, must be enclosed by apostrophes.
The possible values of t are
blank Call the relocatable version of AEDIT$. This is the default if t is omitted.
'CB' Call the common bank version of AEDIT$.
'A' Call the common bank version of AEDIT$ using the Auto Switch method.
Parameters specific to the individual PROC call (see Table 4–1, Table 4–2, and
Table 4–3).
A column pointer is maintained by AEDIT$. It is advanced by the number of characters
the calling program inserts when editing. The first column is zero.
Some AEDIT$ PROCs return an error status in register A1. See the individual PROC calls
in Table 4–1, Table 4–2, and Table 4–3 for possible error status codes. Unless
documented, no error status is returned for the PROC calls.
4.2.1. General-Purpose Editing Routines
The calling program must establish an "edit mode" before using the AEDIT$ routines. The
edit mode begins when the A$EDIT PROC is called, and ends when either the A$EDITX
or A$EPRINT PROCs are called.
Edit mode is reestablished by calling the A$EDITR PROC. A$EDITR assumes that a prior
call to the A$EDITX PROC has been made. If A$EDITR is called without a previous call
to A$EDITX results are unpredictable and may be erroneous.
7833 1733–004 4–7

AEDIT$–ASCII Image Composition Editing Package
The sequence which must be used when calling the AEDIT$ routines is
A$EDIT pkt . Establish edit mode.
A$Exxxx p1,p2 . Call the AEDIT$ PROCs
. to perform editing.
A$EDITX . Terminate edit mode (A$EPRINT also
. terminates edit mode).
. .
. . Other processing may take place here.
. .
A$EDITR pkt . Re-establish edit mode.
A$Exxxx p1,p2 . Perform more editing.
A$EDITR . Terminate edit mode (or A$EPRINT
. to print line and terminate).
Table 4–1 describes the AEDIT$ routines to initialize and terminate edit mode. Table 4–2
and Table 4–3 describe the routines that may be called in edit mode.
The AEDIT$ PROCs pass parameters in registers A0 and A1. If the parameters are
omitted on the call, then the corresponding load instructions are not generated, and
AEDIT$ assumes the input data is in the designated registers. The parameters may be
in the instruction word format "*u,*x,j"which may be defined with the MASM $EQUF
directive ("label $EQUF *u,*x,*j") and the $EQUF label specified as the parameter.
Parameters are indicated by p1 and p2 in Table 4–1 and Table 4–2.
4–8 7833 1733–004

AEDIT$–ASCII Image Composition Editing Package
Table 4–1. AEDIT$: Initialization and Termination Editing Routines
PROC Call Generated
Instructions
A$EDIT p1 LA,XU A0,p1
LMJ X11,AEDIT$
A$EDITR p1 LA,XU A0,p1
LMJ X11,AEDITR$
Description
Initialize and establish edit mode.
p1 is the address of the AEDIT$ packet. If p1 is not specified,
the address of the packet must be in A0. S3 of the first word
of the packet is expected to contain the number of words in the
image area, and H2 of the first word of the packet is expected
to contain the location of the image area. The image is set to
blanks, and edit mode is established. The column pointer is set
to the start of the image. AEDIT$ enters quarter-word mode.
AEDIT$ returns a status code in register A1. If A1 is zero, no
error occurred; if A1 is nonzero, an error occurred and AEDIT$
terminates with an ER ERR$. See Table 4–5 for an explanation
of error status codes.
Reenter edit mode without initializing.
A$EDITX LMJ X11,AEDITX$ Terminate edit mode.
A$EPRINT p1 LA,U A0,p1
LMJ X11,AEPRINT$
If p1 is not specified, the address packet must be in register
A0. Edit mode is reestablished, and the column pointer (saved
by AEDITX$) is restored.
The column pointer is saved in the packet. AEDITX$ returns
with the packet address in A0 and the number of words in the
image in A1.
Print image and leave editing mode (call AEDITX$).
Parameter p1 specifies the line spacing for the image. See the
A$EPRINT description in Table 4–2.
7833 1733–004 4–9

AEDIT$–ASCII Image Composition Editing Package
Table 4–2. AEDIT$: General Purpose ASCII Editing Routines
PROC Call Generated
Instructions
A$ECHAR p1 LA,XU A0,p1
LMJ X11,AECHAR$
Description
Insert the character in p1 into the next position of the data
area.
The character contained in Q4 of A0 is inserted into the data
area.
A$ECLEAR LMJ X11,AECLEAR$ Clear the data area for the ASCII image.
The data area is set to blanks and the column pointer is set to
the start of the data area (column zero).
A$ECOLN LMJ X11,AECOLN Compute the current column number.
A$ECOL p1 LA,XU A0,p1
A$ECOPY
p1,p2
A$EDCFZ
p1,p2
A$EDECF
p1,p2
LMJ X11,AECOL$
LA,U A0,p2
LA,U A1,p1
LMJ X11,AECOPY$
LA A0,p2
LA,U A1,p1
LMJ X11,AEDCFZ$
LA A0,p2
LA,U A1,p1
LMJ X11,AEDECF$
A$EDECV p1 LA A0,p1
LMJ X11,AEDECV$
Returns with the column number in A0.
Position to the column specified in p1.
The column pointer is changed to the number specified in p1.
The first character position of the image is column 0.
Copy a string into the data area.
p2 is expected to contain the address of a string of characters.
A character offset for the first word of the string may be
supplied in H1 of register A0. The offset is in the range 0–3
with 0=Q1, 1=Q2, 2=Q3, and 3=Q4 of the first word.
If the character offset is supplied in H1 of register A0, then the
PROC call should not be used. Instead, the calling sequence
should be coded directly. The number of characters in p1 is
copied from this area into the data area.
Edit a decimal number (fixed length with leading zeros).
Edit p2 to a decimal number right-justified in a field of p1
characters. A leading "-" is added if p2 is negative. The result
overflows the field to the right if it does not fit into the
specified field size.
Leading zeros are produced where AEDECF$ would produce
leading spaces. This routine is convenient for editing decimal
fractions.
Edit a decimal number (fixed length).
Edits p2 to a decimal number right-justified in a field of p1
characters. A leading "--" is added if p2 is negative. The result
overflows the field to the right if it does not fit into the
specified field size.
Edit a decimal number (variable length).
Edits p1 to a decimal number. A leading "-" is added if p1 is
negative. The number of characters generated is a function of
the sign and magnitude of p1.
4–10 7833 1733–004

AEDIT$–ASCII Image Composition Editing Package
Table 4–2. AEDIT$: General Purpose ASCII Editing Routines
PROC Call Generated
Instructions
A$EFD1 p1 LA A0,p1
LMJ X11,AEFD1$
A$EFD2 p1 DL A0,p1
LMJ X11,AEFD2$
A$EMSG p1 LA,U A0,p1
LMJ X11,AEMSG$
Description
Insert one word of ASCII characters.
The four characters in p1 are inserted into the image. ASCII
spaces (040) and null characters (000) are ignored.
Insert two words of ASCII characters.
The eight characters in p1 are inserted into the data area.
Blanks and null characters are ignored.
Message editor initial entry.
A$EMSGR LMJ X11,AEMSGR$ Message editor reentry.
A$EOCTF
p1,p2
LA A0,p2
LA,U A1,p1
LMJ X11,AEOCTF$
A$EOCTV p1 LA A0,p1
A$EPACK
p1,p2
LMJ X11,AEOCTV$
LA,U A0,p2
LA,U A1,p1
LMJ X11,AEPACK$
Copies the characters starting at the address given in p1 into
the data area. This process stops when the character in Q1 of
the sixth word of the packet (stop character) is found. The
pointer to the string is saved in the packet.
The string at address p1 must contain at least one stop
character. A character offset for the first word of the string
may be supplied in H1 of register A0. The offset is in the
range 0–3 with 0=Q1,1=Q2, 2=Q3, and 3=Q4 of the first
word.
If the character offset is supplied in H1 of register A0, then the
PROC call should not be used. Instead, the calling sequence
should be coded directly.
This routine performs the same operation as AEMSG$ except
that the pointer to the input string is taken from the packet.
With these two routines, it is possible to copy a string into the
data area, occasionally interrupting this process to perform
other editing functions at certain selected points in the string.
Edit an octal number (fixed length).
Edits p2 to p1 octal digits. Leading zeros are not suppressed.
P1 must not exceed 12.
Edit an octal number (variable length).
Edits contents of p1 to octal. The number of digits edited
depends on the size of the number. If the number is greater
than seven, a leading zero is added.
Copy and pack a string.
Same as A$ECOPY except that null (000) characters are
ignored. A$QPACK removes the null (000) characters from the
output string while A$ECOPY retains them. Null characters do
not show up in the printed line.
7833 1733–004 4–11

AEDIT$–ASCII Image Composition Editing Package
Table 4–2. AEDIT$: General Purpose ASCII Editing Routines
PROC Call Generated
Instructions
A$EPACK
p1,p2
A$EPRINT p1 LA,U A0,p1
LA,U A0,p2 Copy and pack a string.
LMJ X11,AEPRINT$
A$ESKIP p1 LA,XU A0,p1
LMJ X11,AESKIP$
Print image line and AEDITX$.
Description
The image pointed to by the image location in the packet is
printed and AEDITX$ performed. The line spacing is given in
p1. If the parameter is omitted, a value of one is used.
The AEDIT$ routines do not limit the size of the image that can
be created. However, the size of the image that can be
printed is limited by both the AEPRINT$ routine and the
current print width.
The AEPRINT$ routine has a limit of 63 words or 252 ASCII
characters. If the image contains more than 63 words,
AEPRINT$ prints the first 63 words and ignores the extra
words.
The print width is a control parameter for the Exec printer
handlers. If the length of the image is greater than the current
print width, a type 02 (SYMB) code 04 (SDF image length
error) contingency occurs.
The standard default value for print width is 33 words or 132
ASCII characters. To print an image larger than this, you must
increase the print width by using the print control 'W' function.
Refer to the Exec Request Programming Reference Manual for
a description of the print control functions.
Note: To establish the print width for the maximum size
image that can be output by AEPRINT$ (63 words or 252 ASCII
characters), issue a print control "W,42" function. With this
print width, no contingency due to length error will ever occur
when using AEPRINT$. This is because AEPRINT$ prints a
maximum of 63 words of image data and ignores any words
beyond 63.
Advance the column pointer.
The number given in p1 is added to the column pointer.
p1 may be negative.
4–12 7833 1733–004

AEDIT$–ASCII Image Composition Editing Package
Example
The following example shows a MASM program that generates an ASCII string by calling
the relocatable version of AEDIT$.
$ASCII
$INCLUDE ‘MAXR$’
$(2)
LINE $RES 20 . Data area for image
PACKET A$EDITPKT 20,LINE . AEDIT$ packet
STRING ‘The contents of variable’ . ASCII character string
VAR ‘ADDRESS’ . Variable name
VALUE + 02741 . Octal value for variable
$(1)
START
A$EDIT PACKET . Initialize and enter ASCII editing mode
A$ECOL 10 . Move to column 10
A$ECOPY 24,STRING . Copy 24 characters from string to the data area
A$ECHAR ‘

AEDIT$–ASCII Image Composition Editing Package
4.2.2. Floating-Point Editing Routines
AEDIT$F edits floating-point numbers into one of two general formats.
• Fixed decimal format (no exponent)
• Scientific format
Fixed Decimal Format
A number edited in fixed decimal format consists of a sign (if negative) followed by the
digits of the number with an embedded decimal point. The sign is present only if the
number is negative; a positive number has no sign character.
The floating-point editing routines require three parameters in addition to the address of
the floating-point packet. The first two are called x and y and are supplied in S5 and S6
of register A0. They specify the format of the edited number as described below. The
third parameter is the single- or double-precision number to be edited. If single
precision, the number is specified in A1; if double precision, the number is specified in
registers A1 and A2.
The x parameter specifies the width of the edited field; in other words, the number of
character positions that the edited number will occupy, including sign and decimal point.
If the value of x is too small to represent the value being edited, it is ignored, and as
many character positions are used as are required to correctly represent the number.
The y parameter specifies how many fractional digits will be edited. This is the number
of digits appearing to the right of the decimal point. The value of y may be any value
greater than or equal to zero, but should always be less than the value of x to allow for
the sign and decimal point characters.
The maximum number of significant digits for which the floating-point routines can
generate correct results in the fixed decimal format is 8 for single-precision numbers and
17 for double precision. It includes digits on both the sides of the decimal point. This is
because the 2200 single-precision floating-point format uses 27 bits for mantissa which
can represent up to 8 decimal digits. The double-precision floating-point format uses 60
bits for the mantissa which can represent up to 18 decimal digits. Rounding can be done
at a maximum of the 18th digit. This will provide rounded results up to 17 digits. If the
rounding option has been set with a value of y greater than 17 rounding will not be done
by these routines.
For example, the following numbers are in fixed decimal format:
258.61 Requires parameter values of x > 6 and y = 2.
-85.2239 Requires parameter values of x > 8 and y = 4.
1093. Requires parameter values of x > 5 and y = 0.
4–14 7833 1733–004

AEDIT$–ASCII Image Composition Editing Package
Scientific Format
The scientific format is similar to the fixed decimal format, but it has an exponent at the
right. The exponent consists of an optional exponent character (usually 'E' for singleprecision
and 'D' for double-precision numbers) followed by the exponent's sign (either
"+" or "-") and the exponent's digits. Exponents of single-precision numbers are always
edited as a 2-digit value, and those of double-precision numbers are always edited as a
3–digit value.
The x parameter specifies the total number of character positions to be occupied by the
edited number, including signs, digits, decimal point, and exponent character. If the
edited numbers require more character positions than are specified by the value of x, the
x parameter is ignored and the required character positions are used.
The y parameter specifies the total number of mantissa digits to appear in the edited
number. It includes the digits on both sides of the decimal point but not the decimal
point itself. The placement of the decimal point within the y digits of the mantissa is
determined by the value in the packet cell fps. This is the number of digits to appear to
the left of the decimal point. It is normally set to one.
The floating-point routines provide rounding up to 8 significant digits for single-precision
floating-point numbers and 17 significant digits for double-precision floating-point
numbers. This is because the 2200 single-precision and the double-precision formats
use 27 and 60 bits for the mantissa, respectively. These can represent up to 8 and 18
significant digits in these cases. As rounding is done at a maximum of the 18th digit, the
maximum value of y for which a rounded result will be produced is 8 for single-precision
and 17 for double-precision floating-point numbers. The value of x should allow for the
sign, decimal point, the exponent character, the exponent sign, and the exponent digits.
For example, the following numbers are in scientific format:
8.66E+01 Requires parameter values of x ≥ 8 and y = 3.
-1.3375E-10 Requires parameter values of x ≥ 11 and y = 5.
5.164D+003 Requires parameter values of x ≥ 10 and y = 4.
7833 1733–004 4–15

AEDIT$–ASCII Image Composition Editing Package
4.2.2.1. Calling Procedures for the Floating-Point Editing Routines
Table 4–3 describes the floating-point editing routines and the procedures used to call
them.
Table 4–3. AEDIT$F: Floating-Point ASCII Editing Routines
PROC Call Generated
Instructions
A$EFLF1 x*/6+y,p LA A1,p
LA,U A0,x*/6+y
LMJ X11,AEFLF1$
A$EFLF2 x*/6+y,p DL A1,p
LA,U A0,x*/6+y
LMJ X11,AEFLF2$
A$EFLG1 x*/6+y,p LA A1,p
LA,U A0,x*/6+y
LMJ X11,AEFLG1$
A$EFLG2 x*/6+y,p DL A1,p
LA,U A0,x*/6+y
LMJ X11,AEFLG2$
A$EFLS1 x*/6+y,p LA A1,p
LA,U A0,x*/6+y
LMJ X11,AEFLS1$
A$EFLS2 x*/6+y,p DL A1,p
LA,U A0,x*/6+y
LMJ X11,AEFLS2$
Description
Single-precision fixed decimal format.
The floating-point number p is edited to fixed
decimal format with y digits following the decimal
point, right-justified, in a field of size x.
Double-precision fixed decimal format.
The floating-point number p is edited to fixed
decimal format with y digits following the decimal
point, right-justified, in a field of size x.
Single-precision generalized format.
Same as scientific format except that an attempt is
made to move the decimal point in such a way as to
reduce the exponent to zero. If this can be done,
the exponent is set to blanks. Otherwise scientific
format is used.
Double-precision generalized format.
See AEFLG1$ and AEFLS2$.
Single-precision scientific format.
The floating-point number p is edited to scientific
format with y significant digits in a field size of x.
The exponent is two digits long.
Double-precision scientific format.
The floating-point number p is edited to scientific
format with y significant digits in a field size of x.
The exponent is three digits long.
4–16 7833 1733–004

4.2.2.2. Example
AEDIT$–ASCII Image Composition Editing Package
The following example shows a MASM program that generates an ASCII string
containing floating-point numbers with the common bank version of AEDIT$.
$ASCII
$INCLUDE ‘MAXR$’
$(2)
PACKET A$EDITPKT 20,LINE ‘FPS’,0 ‘SPC’,’E’ . AEDIT$ packet
LINE $RES 20 . Image buffer
DIVIDEND + 1.0 . Floating-point 1.0
DEC1 + 1 . Integer 1
DIVISOR + 32.0 . Floating-point 32.0
DEC32 + 32 . Integer 32
QUOTIENT + 0 . Quotient location
STRING ‘ divided by ‘
$(1)
START
A$EDIT,’CB’ PACKET . Enter ASCII edit mode
A$EDECV,’CB’ DEC1 . Edit ASCII ‘1’
A$ECOPY,’CB’ 12,STRING . Copy 12 characters
A$EDECV,’CB’ DEC32 . Edit ASCII ‘32’
A$ECHAR,’CB’ ‘

AEDIT$–ASCII Image Composition Editing Package
The floating-point number at location DIVIDEND is divided by the floating-point number
at location DIVISOR and stored at the location QUOTIENT. The A$EFLS1 procedure
edits the quotient into scientific format. The total number of characters used is 11. Five
of these characters are used for digits.
The A$EPRINT procedure prints the image generated at location LINE by executing an
ER APRINT$ and exits edit mode.
4.2.3. Time and Date Editing Routines
PROC Call
A$EDAY1 p1
A$EDAT1
A$EDAY2 p1
A$EDAT2
A$EDAY3 p1
A$EDAT3
AEDIT$T provides ASCII time and date editing to common formats.
Each of these functions accepts input in ER TDATE$ format. (See the Exec ER
Programming Reference Manual.)
month day year (relative to
1964)
number of seconds since midnight
Table 4–4. AEDIT$T: ASCII Time and Date Editing Routines
Generated
Instructions
LA A0,p1
LMJ X11,AEDAY1$
ER TDATE$
LMJ X11,AEDAY1$
LA A0,p1
LMJ X11,AEDAY2$
ER TDATE$
LMJ X11,AEDAY2$
LA A0,p1
LMJ X11,AEDAY3$
ER TDATE$
LMJ X11,AEDAY3$
Description
Edits the date portion of A0 into the format
mm/dd/yy
where mm, dd, yy are the 2 digits of the month, day, and year,
respectively.
Edits the date portion of A0 into the format
dd mmm yy
where dd and yy are the 2 digits of the day and year,
respectively, and mmm is a 3-character abbreviation for the
month.
Edits the date portion of A0 into the format
month dd, year
where month is the name of the month (up to 9 characters), dd is
the day (1 or 2 characters), and year is the 4-digit year.
4–18 7833 1733–004

PROC Call
A$EDAY4 p1
A$EDAT4
A$EDAY5 p1
A$EDAT5
A$ETIME p1
A$ETD
AEDIT$–ASCII Image Composition Editing Package
Table 4–4. AEDIT$T: ASCII Time and Date Editing Routines
Generated
Instructions
LA A0,p1
LMJ X11,AEDAY4$
ER TDATE$
LMJ X11,AEDAY4$
LA A0,p1
LMJ X11,AEDAY5$
ER TDATE$
LMJ X11,AEDAY5$
LA A0,p1
LMJ X11,AETIME$
ER TDATE$
LMJ X11,AETIME$
Description
Edits the date portion of A0 into the format
yearmmdd
where year is the 4-digit year, and mm and dd are the 2 digits of
the month and day, respectively.
Edits the date portion of A0 into the format
yymmdd
where yy, mm, and dd are the 2 digits of the year, month, and
day, respectively.
Edits the time portion of A0 into the format
hh:mm:ss
where hh, mm, and ss are the 2 digits of the hours, minutes, and
seconds of the time, respectively.
4.2.4. Standard Format Date and Time Editing Routines
AEDIT$SFDT is a routine that creates an ASCII string using standard formats for date and
time. The current date and time (or caller-specified date and time) are converted into an
ASCII string and placed into the buffer that the calling program provides. This routine is
used like the other AEDIT$ routines.
There are eight system standard date formats and three system standard time formats:
Date Formats Time Formats
1. YYMMDD 1. HHMM
2. CCYYMMDD 2. HHMM:SS
3. YY-MM-DD 3. HHMM:SS.FFF
4. CCYY-MM-DD
5. YY mmm DD
6. CCYY mmm DD
7. YY mmm DD ddd
8. CCYY mmm DD ddd
7833 1733–004 4–19

AEDIT$–ASCII Image Composition Editing Package
where:
CC
YY
MM
DD
HH
MM
SS
FF
mmm
ddd
Two-digit decimal century
Two-digit decimal year of century
Two-digit decimal month
Two-digit decimal day of month
Two-digit decimal hour
Two-digit decimal minute
Two-digit decimal second
Three-digit decimal fractional second (only significant digits included)
Three ASCII character abbreviation for month (see 22.3, SFDTBL$)
Three ASCII character abbreviation for day of week (see 22.3, SFDTBL$)
The calling program can edit an individual date, individual time, or combined date and
time format. If combined together, the date format precedes the time format, and the
date and time are separated by either a space character (' ') or a dash character ('–'). The
space character separator may be used with all formats. The dash character separator
may only be used with date formats 1 through 4.
4–20 7833 1733–004

4.2.4.1. Recommended Date and Time Formats
AEDIT$–ASCII Image Composition Editing Package
Since there are many possible date and time format combinations, the following formats
are recommended as standard:
YYMMDD HHMM:SS format (1,2) (most compact)
CCYY-MM-DD HHMM:SS format (4,2)
CCYY mmm DD ddd HHMM:SS format (8,2) (most descriptive)
The element SFDTBL$ contains the ASCII character abbreviations for months and days.
It is accessed by the external label SFDTBL$. These abbreviations may be changed to
other abbreviations for months and days, for example, when using languages other than
English.
4.2.4.2. Calling Procedure for Date and Time Editing
The following procedure calls the ASCII system standard format date and time editing
routine:
A$ESFDT[,t] [date] [time]
error return
normal return
where:
t
date
The type of call to AEDIT$SFDT: This parameter is optional and may be omitted.
CB or A, if specified, must be enclosed by apostrophes.
blank
'CB'
'A'
Call the relocatable version of AEDIT$SFDT. This is the default if t is omitted.
Call the common bank version of AEDIT$SFDT.
Call the common bank version of AEDIT$SFDT using the Auto Switch method.
The address of a caller-specified date and time. If specified, it must be in TDATE$
format. This parameter is optional.
7833 1733–004 4–21

AEDIT$–ASCII Image Composition Editing Package
time
The address of a caller-specified time. If specified, it must be in TIME$ format.
This parameter is optional.
If date or time are not included on the calling statement, the current date and time is
used (from ER TDATE$ or current time from ER TIME$ for time format 3). Indexing,
incrementation, indirect addressing, and j-designator selection in the format “*u,*x,j”
may be used to specify date and time if they are defined with the MASM $EQUF
directive ("label $EQUF *u,*x,j") and the $EQUF label is specified as the parameter.
The calling program specifies the date format index and time format index in the AEDIT$
packet. See 4.1.1.
If an error occurs, the error return is taken, and register A1 contains one of the error
codes in Table 4–5. The code is also stored in the packet in field “error code” (see
4.1.1).
If the normal return is taken, the date and time string has been successfully stored in the
caller's data area.
The generated instructions for the relocatable call, if both date and time parameters are
present:
L A0,date
L A1,time
LMJ X11,AESFDT$
4–22 7833 1733–004

4.2.4.3. Example
AEDIT$–ASCII Image Composition Editing Package
The following example shows a MASM program that creates an ASCII string with date
and time formats using the relocatable version of AEDIT$.
$ASCII
$INCLUDE ‘MAXR$’
$(2)
PKT A$EDITPKT 15,DATELINE ‘DFT’,8 ‘TFT’,3 . AEDIT$ packet
DATELINE $RES 15 . Image buffer
MSG ‘Current date and time:’ . Output string
$(1)
START
A$EDIT PKT . Enter edit mode
A$ECOPY 23,MSG . Copy 23 character string
A$ESFDT . Edit the date and time
J ERROR . Jump if error occurred
A$EPRINT . Print out edited string
J DONE .
ERROR . Error return
L$SNAP ‘SFDT’,2 . Dump A-registers
DONE .
ER EXIT$
$END START
This MASM program calls the relocatable version of AEDIT$ to create and print the
following ASCII string:
Current date and time: 1983 Sep 10 Sat 1643:14.057
In this example, AEDIT$ generates the ASCII string in the 15-word data area DATELINE.
The AEDIT$ packet is generated by the A$EDITPKT procedure using date format 8 and
time format 3.
The A$EDIT procedure initializes the AEDIT$ packet at location PKT and enters edit
mode. The A$ECOPY procedure copies 23 characters from location MSG to the data
area (including one space character following the colon). The A$ESFDT procedure call
generates the standard date and time format string in the data area. Since no date or
time parameters are specified on the A$ESFDT procedure call, the current date and time
are used.
If A$ESFDT takes the error return, the A-registers are dumped by the L$SNAP procedure
call. Otherwise, the A$EPRINT procedure prints the image generated at location
DATELINE by executing an ER APRINT$. Edit mode is then exited.
7833 1733–004 4–23

AEDIT$–ASCII Image Composition Editing Package
4.2.5. Error Status Codes
The status codes listed in Table 4–5 are returned in register A1 when an error occurs in
some of the AEDIT$ routines.
Table 4–5. AEDIT$: Error Status Codes
Octal Code Status
0 Normal return from A$ESFDT.
01 A prelevel 75R1 SYSLIB AEDIT$ packet format is being used.
02 An outdated version of the AEDIT$ packet is being used.
03 The date format index is out of range.
04 The time format index is out of range.
05 Both of the date and time formats are zero.
06 The common bank version of AEDIT$ is being called without
using the A$EDITPKT PROC to generate the AEDIT$ packet.
4–24 7833 1733–004

4.2.6. Examples
AEDIT$–ASCII Image Composition Editing Package
The following table contains examples of AEDIT$ PROC calls and the instructions that
the PROC call generates.
Procedure Call Generated Instructions
A$ECHAR ‘A’ LA,U A0,’A’
LMJ X11,AECHAR$
A$ECHAR *TAG,X6,S5 LA,S5 A0,*TAG,X6
LMJ X11,AECHAR$
A$ECHAR,’CB’ I$BJ X11,CBAECHAR$
A$EDECV COUNT,,H2 LA,H2 A0,COUNT
LMJ X11,AEDECV$
A$EDECV LMJ X11,AEDECV$
A$ECOPY 50,LINE LA,U A0,LINE
LA,U A1,50
LMJ X11,AECOPY$
A$ECOPY 50,TAB,X6,W LA A0,TAB,X6
LA,U A1,50
LMJ X11,AECOPY$
A$ECOPY COUNT LA,U A1,COUNT
LMJ X11,AECOPY$
A$EDECF,’A’ 10,COUNT LA A0,COUNT
LA,U A1,10
LMJ X11,CBAEDECF$-1
A$EFLF2 30*/6+18,(1.234D) DL A1,(1.234D)
LA,U A0,30*/6+18
LMJ X11,AEFLF2$
A$EFLF1 20*/6+9 LA,U A0,20*/6+9
LMJ X11,AEFLF1$
7833 1733–004 4–25

AEDIT$–ASCII Image Composition Editing Package
4–26 7833 1733–004

Section 5
BSP$-Program File Basic Service
Package
The Basic Service Package (BSP$) provides an interface between the calling program
and the table of contents (TOC) of a program file.
The program file format is described in the Data Structures Programming Reference
Manual. The file table index (FTI) is the control part of the program file. Figure 5-1
contains a general description of the FTI. The FTI describes five tables that are accessed
by the BSP$ functions.
• Element table
• Assembler procedure table
• COBOL procedure table
• FORTRAN/PLUS procedure table
• Relocatable element entry point table
The part of the program file occupied by the five tables is called the TOC.
BSP$ performs the following functions:
• Reads the FTI into a buffer.
• Reads a selected program file table into a buffer.
• Searches a selected program file table for a specific entry.
• Deletes a specific entry in a program file table.
• Locates a program file table entry from its sequence number in the table.
• Changes a specific entry in a program file table.
• Adds an entry to a program file table.
• Writes the last entry referenced back to the file.
• Marks the last entry referenced in a program file table as having been updated.
• Writes a program file table back to the file.
• Writes the FTI back to the file.
Reading the FTI of a previously unwritten file changes that file to a program file. The
table is not written to the file until BSP$ writes the FTI.
7833 1733–004 5–1

BSP$-Program File Basic Service Package
Some guidelines concerning the use of BSP$ are the following:
• There are two basic program file formats. The standard program file (PF) has small
variable-length tables. The large program file (LPF) has large fixed-length tables. For
example, the PF has a normal maximum of 2,671 element table entries that can be
expanded to 5,000 entries, while the LPF has a fixed maximum of 26,146 element
table entries.
• PF and LPF elements are limited to a maximum of 262,143 sectors of text for each
element. A new program file type, the large element program file (LEPF) removes
this limitation and allows elements to have over 262,143 sectors of text, if desired.
An LEPF can be initialized with the small variable-length format of a standard
program file (standard LEPF) or with the large fixed-length format of a large program
file (large LEPF).
• If the calling program attempts to create a program file in a file area in which a file
was previously written, the calling program will receive an error return if the first
word encountered is not the program file identifier constant or if sector 0 is not all
zeros.
• For standard PF format, each table on mass storage begins at the system-defined
sector or at a greater sector if a previous table occupies the defined sector. The
element table always starts at the system-defined sector. The system-defined
sectors and starting sector for element text are the six ‘PFxx$' equates in element
SYS$DEF (see Table 2–4).
• For LPF formats, each table on mass storage begins at the system-defined sector.
The system-defined sectors and starting sector for element text are the six 'LPF$xx'
equates in element SYS$DEF (see Table 2–4).
• For standard PF formats, the system default TOC size is 1,792 sectors (28 tracks).
For LPF formats, the system default TOC size is 40,256 sectors (629 tracks).
• The calling program must provide a 43-word data area (for BSP$). This area is
referred to as the file control table (FCT). The calling program must also provide
main storage buffers for each table read.
• The calling program must request to read the FTI before any other BSP$ functions
are called. The FTI must be in the BSP$ FCT until all BSP$ functions are executed.
• The FTI part of the FCT data area is used by BSP$ to contain necessary information
about the file.
• A table must be read into the caller’s buffer (RPFxxT$ calls) before any operations
are performed on the table.
• BSP$ returns an error code if a table cannot hold another item.
• A table must be written back from the caller's buffer (WPFxxT$ calls) before the
buffer can be used to hold another table.
• BSP$ operates most efficiently when the caller’s buffer is large enough to contain
the entire program file table, including the size of entries to be added to the table.
The current length of each program file is available when the FTI is read.
• Each table that has been modified must be written back to the program file table of
contents on mass storage.
5–2 7833 1733–004

BSP$-Program File Basic Service Package
BSP$ is available in both the SYSLIB common bank SYSLIB$1 and as a relocatable
element in the SYSLIB installation file (SYS$LIB$*SYSLIB). The relocatable and common
bank entry points to BSP$ are listed in Appendix E.
5.1. BSP$ Functions
The following descriptions of the BSP$ functions include three calling methods:
relocatable, common bank, and Auto Switch. Entry points to the common bank BSP$
are the same as the relocatble entry points except they are prefixed with the letters CB.
Section 3 describes the SYSLIB access methods.
Some BSP$ functions require that the address of a packet be passed as a parameter.
In those cases, a diagram shows the format of the packet. If a field name is italicized,
the caller must provide a value for the field. All element, version, and procedure names
are 12 Fieldata characters, left-justified and space-filled. DF is the delete flag and is set
to one for deleted items. CI is the continuation indicator and is set to one for COBOL
procedure names longer than 12 characters.
5.1.1. Read FTI
The FTI must be read into the data area provided by the caller for the FCT before any
other operations can be performed. If any add, delete, or change operations are
completed, then a WFTI$ call must be done to write the FTI back to the file.
Two functions are available to read the FTI. The RFTI$ function can be used to read an
existing PF or LPF and to initialize an empty file as a PF. The RFTI$$ function, described
later in this section, can be used to read an existing PF, LPF, or LEPF and to initialize an
empty file as a PF, LPF, or LEPF.
The following describes the RFTI$ function:
Calling Sequence
Auto Switch
L,U A0,address-of-FCT
LMJ X11,CBRFTI$-1
error return
normal return
Common Bank or
Relocatable
L,U A0,address-of-FCT
I$BJ X11,CBRFTI$
error return
normal return
Relocatable
L,U A0,address-of-FCT
LMJ X11,RFTI$
error return
normal return
7833 1733–004 5–3

BSP$-Program File Basic Service Package
Parameters
address-of-FCT
Address of data area for BSP$. This data area requires 43 words. Words 0 and 1
must contain an internal file name that is in the Fieldata character set, left-justified,
and space-filled. This data area is referred to as the FCT, and must not be modified
between calls to BSP$ after it has been initialized by RFTI$.
Returns
error return
A0 has one of the following values:
02
04
05
07
010
File is not a program file.
File is not assigned to the run or is not a sector formatted mass storage file.
Program file does not contain a supported revision level.
No starting sector address for large program file table.
Program file does not contain a valid size indicator.
07700000000nn
normal return
nn is error status from ER IOW$.
The FTI is stored in the file control table starting at word FCT+6. The FTI is initialized
in the FCT if an I/O status 05 was returned as RFTI$ attempted to read from the file
name specified in words 0 and 1 of the FCT. If the caller is going to be adding an
element to the file, the next sector location for writing the text of the element is
found at word FCT + 7.
On return, A1, S6 (bits 30 through 35) has the FTI size indicator. A PF will have a
value of 0. An LPF will have a value of 4. A1, bit 29 (octal 0100) is the large-element
text-allowed bit. Since RFTI$ can only be used to access a PF or LPF, bit 29 is
always zero (clear). A1 bits 0 through 28 are always zero.
5–4 7833 1733–004

BSP$-Program File Basic Service Package
Figure 5–1 indicates the arrangement of the program file control table after the FTI is
read.
Figure 5–1. BSP$: File Control Table (FCT)
7833 1733–004 5–5

BSP$-Program File Basic Service Package
The following describes the RFTI$$ function:
Calling sequence
Auto Switch
L,U A0,address-of-FCT
L A1,(BSP$-int-level, lengthof-FCT)
L,U A2,[large-elt text++]sizeindicator
LMJ X11,CBRFTI$$-1
error return
normal return
Parameters
address-of-FCT
Common Bank or
Relocatable
L,U A0,address-of-FCT
A1(BSP$-int-level, lengthof-FCT)
L,U A2,[large-elt text++]sizeindicator
I$BJ X11,CBRFTI$$
error return
normal return
Relocatable
L,U A0,address-of-FCT
L,U A1,(BSP$-int-level, lengthof-FCT)
LMJ A2,[large-elt text++]sizeindicator
LMJ X11,RFTI$$
error return
normal return
Address of data area for BSP$. This data area requires at least 43 words. A data
area of 56 words is recommended to accommodate future BSP$ expansion. Words
0 and 1 of this data area must contain an internal file name that is in Fieldata, leftjustified,
and space-filled. This data area is referred to as the file control table (FCT)
and must not be modified between calls to BSP$ after it has been initialized by
RFTI$$.
BSP$-int-level
The BSP$ interface level required by the calling program. The following values may
be specified:
0 This is the only value supported prior to SYSLIB 76R1. It allows access to an
existing PF or LPF and allows an empty file to be initialized as a PF or LPF.
1 This value allows access to an existing PF, LPF or LEPF and allows an empty
file to be initialized as a PF, LPF or LEPF. Note that special care must be
taken when processing elements and element text in an LEPF. See sections
5.1.7 and 5.3 for additional information.
2 This value is supported beginning with SYSLIB 76R3. Allows the same file
access and initialization as interface level 1. In addition, returns an indication if
the program file was initialized on this function call.
length-of-FCT
Length in words of the data area provided in register A0.
5–6 7833 1733–004

large-elt-text
BSP$-Program File Basic Service Package
The optional large-element text-allowed control bit is bit 29 (octal 0100) in register
A2. It is used by BSP$ only if an empty file is to be initialized as a program file. If bit
29 is zero (clear), the program file is initialized as a PF or an LPF (as specified by
size-indicator) and elements are limited to 262,143 sectors of element text each. If
this bit is one (set), the program file is initialized as a standard LEPF or a large LEPF
(as specified by size-indicator) and elements are allowed to have over 262,143
sectors of element text each. Note that bit 29 cannot be set unless BSP$ interface
level is at least 1.
size-indicator
Size-indicator is in register A2, S6 (bits 30 through 35). It is used by BSP$ only if an
empty file is to be initialized as a program file and its value determines the format of
the program file. The following values may be specified:
0 Standard PF format.
1 Alternate, unsupported standard PF format. A value of 0 will be substituted.
2 Alternate, unsupported LPF format. A value of 4 will be substituted.
3 Alternate, unsupported LPF format. A value of 4 will be substituted.
4 LPF format.
For values 0 and 1, an empty file will be initialized as a PF if large-elt-text is clear and
as a standard LEPF if large-elt-text is set and if BSP$-int-level is at least 1. For values
2, 3, and 4, an empty file will be initialized as an LPF if large-elt-text is clear and as a
large LEPF if large-elt-text is set and if BSP$-int-level is at least 1.
Returns
error return
A0 has one of the following values:
01
02
03
Specified length of data area for FCT (length-of-FCT) is less than the minimum
required.
File is not a PF.
Specified BSP$ interface level (BSP$-int-level) is not supported by this level of
SYSLIB.
7833 1733–004 5–7

BSP$-Program File Basic Service Package
04
05
06
07
010
File is not assigned to the run or is not a sector formatted mass storage file.
PF does not contain a supported revision level.
Specified size indicator (size-indicator) is illegal.
No starting sector address for LPF table.
PF does not contain a valid size indicator.
07700000000nn
normal return
nn is error status from ER IOW$.
The FTI is stored in the FCT starting at word 6 (see Figure 5–1). The FTI is initialized if
the file was empty (I/O status 05) or if the first sector was zeroes. If the caller is
going to be adding an element to the file, the next sector location for writing element
text is found at word FCT+7.
On return A1, S6 (bits 30 through 35) has the FTI size indicator. A standard PF (PF or
standard LEPF) will have a value of 0. An LPF (LPF or large LEPF) will have a value
of 4.
On return A1, bit 29 (octal 0100) is the large-element text-allowed bit. For a PF or
LPF, bit 29 is zero (clear). For an LEPF, bit 29 is one (set).
On return when the BSP$ interface level specified on the RFTI$$ function call is 0 or
1, A1, bit 28 (octal 0200) is zero (clear). On return when the BSP$ interface level
specified on the RFTI$$ function call is 2 or more, A1, bit 28 is the program file
initialized bit. If the file was already a program file, bit 28 is zero (clear). If the file was
empty and was initialized as a program file, bit 28 is one (set).
On return A1, bits 0 through 27 are zeroes.
5–8 7833 1733–004

Example of Using RFTI$$
BSP$-Program File Basic Service Package
The following code fragment illustrates an RFTI$$ calling sequence:
L,U A0,FCT . Address of the File Control Table
L A1,(1,56) . BSP$ interface level 1, 56 word FCT
L,U A2,0100++4 . Initialize empty file to allow large
. element text and as a large program
. file (large LEPF)
I$BJ X11,CBRFTI$$ . Call common banked BSP$
J BSPERR . Error on FTI read/initialize
. Proceed on normal return
5.1.2. Read Program File Table
This table must be read into the calling buffer before any operations are performed on
the table. If any add delete, or change operations were completed, then the table must
be written back to the file with one of the WPFxxT$ calls.
The BSP$ entry points for reading program file tables are
(CB)RPFET$ Read Program File Element Table
(CB)RPFAPT$ Read Program File Assembler Procedure Table
(CB)RPFCPT$ Read Program File COBOL Procedure Table
(CB)RPFEPT$ Read Program File FORTRAN/PLUS Procedure Table
(CB)RPFEPT$ Read Program File Relocatable Element Entry Point Table
Calling Sequence
Auto Switch Common Bank or
Relocatable
L,U A0,address-of-FCT
L A1,(buffer, length)
LMJ X11,CBRPFxxT$-1
error return
normal return
L,U A0,address-of-FCT
L A1,(buffer, length)
I$BJ X11,CBRPFxxT$
error return
normal return
Relocatable
L,U A0,address-of-FCT
L,U A1,(buffer, length)
LMJ X11,RPFxxT$
error return
normal return
7833 1733–004 5–9

BSP$-Program File Basic Service Package
Parameters
buffer
length
The starting address of the buffer that is used for the table.
The length in words of the buffer area reserved for the PF table. Only lengths of 196
words (7 sectors), 224 words (8 sectors), and 28* (5+4n) words (5+4n sectors),
where n is a positive integer, are used by BSP$. The specified length will be
rounded down to the next lower buffer length, if necessary. Only this adjusted
buffer length will be read and written by BSP$. A minimum buffer length of 28*
(5+4*2) or 364 is recommended. For maximum efficiency, the buffer length should
be large enough to contain the entire PF table, including the size of table entries to
be added. The starting address of the buffer plus the length must be less than or
equal to 0777777.
Returns
error return
A0 has one of the following values:
012
013
024
025
044
User does not have FTI in main storage.
No starting sector for large program file table.
User buffer too small. The buffer length should be at least 252 words.
User buffer too large. The starting address of the buffer plus the length of the
buffer exceeded 0777777.
No room in file to create this table.
7700000000xx
I/O error, where xx is the I/O status returned.
5–10 7833 1733–004

normal return
BSP$-Program File Basic Service Package
The buffer is filled with the requested table as read from the PF. If the table length
in words in the FTI is 0214 (the size of the pointer table) or less, the requested table
will not be read from the PF but instead the buffer will be initialized. Buffer
initialization means that the requested table will have its pointer table cleared to zero
and its control word set. H1 of the control word will contain the length of the items
comprising the requested table, and H2 will contain zero for the number of table
items.
5.1.3. Search Table for Requested Item
The search table items are
(CB)ETIS$ Element Table Item Search
(CB)APTIS$ Assembler Procedure Table Item Search
(CB)CPTIS$ COBOL Procedure Table Item Search
(CB)FPTIS$ FORTRAN/PLUS Procedure Table Item Search
(CB)EPTIS$ Relocatable Element Entry Point Table Item Search
Calling Sequence
Auto Switch
L,U A0,address-of-FCT
L,U A1,address-of-searchpacket
LMJ X11,CBxxIS$-1
error or no find
normal return
Returns
error return
A0 has one of the following values:
04
Illegal pointer link
Common Bank or
Relocatable
L,U A0,address-of-FCT
L,U A1,address-of-searchpacket
I$BJ X11,CBxxIS$
error or no find
normal return
Registers returned when A0 = 04
A1 = address of search packet
A2 = 0 or previous sequence number containing bad link
A3 = address of table descriptor in FCT
Relocatable
L,U A0,address-of-FCT
L,U A1,address-of-searchpacket
LMJ X11,xxIS$
error or no find
normal return
7833 1733–004 5–11

BSP$-Program File Basic Service Package
012
A4 = 0 or link identifier (1=pointer, 2=type, 3=version)
A5 = sequence number out of range
No FTI
7700000000xx
no find return
I/O error, where xx is the I/O status returned
A0 has one of the following values:
001
011
021
041
A1 = 0
Pointer table
Pointer link
Type link
Version link
A2 = sequence number of last item referenced
normal return
A0 = item location in buffer (that table was previously read into using RPFxxT$).
A1 = sequence number of item
A2
The first half of A2 (H1) is the link type and has one of the following values:
0 Pointer Table
1 Pointer Link
2 Type Link
3 Version Link
5–12 7833 1733–004

BSP$-Program File Basic Service Package
The second half of A2 (H2) contains 0 or the sequence number of the pointing
item.
Packet Formats for Table Item Search
All elements, versions, and procedure names in the following packets are 12 Fieldata
characters, left-justified and space-filled. DF is the delete flag; it is set to 1 if searching
for deleted items.
• Element Table Item Search Packet
0 11 12 17 18 35
0 element name
1
2 zeros
3 D
F
zeros element type zeros
4 version name
5
• Assembler, FORTRAN, or PLUS Procedure Table Item Search Packet
0 35
0 procedure name
1
2 zeros
3 D
F
zeros
7833 1733–004 5–13

BSP$-Program File Basic Service Package
• COBOL Procedure Table Item Search Packet
The first four words are always present in the search packet. The second four
words are present only if the COBOL procedure name exceeds 12 characters and
word 3 bit 1 (CI) is 1.
0 1 2 35
0 COBOL procedure name (first 12 characters)
1
2 zeros
3 D
F
C
I
4 COBOL procedure name (second 12 characters)
5
6 zeros
7 COBOL procedure name (last 6 characters)
• Entry Point Table Item Search Packet
5–14 7833 1733–004
zeros
0 35
0 entry point name
1
2 zeros
3 D
F
zeros
5.1.4. Delete Item from Requested Table
The BSP$ entry points for deleting program file table items are
(CB)ETID$ Element Table Item Delete
(CB)APTID$ Assembler Procedure Table Item Delete
(CB)CPTID$ COBOL Procedure Table Item Delete
(CB)FPTID$ FORTRAN/PLUS Procedure Table Item Delete
(CB)EPTID$ Relocatable Element Entry Point Table Item Delete

Calling Sequence
BSP$-Program File Basic Service Package
Auto Switch Common Bank or Relocatable Relocatable
L,U A0,address-of-FCT
L,U A1,address-of-deletepacket
LMJ X11,CBxxID$-1
error return or no find
return
normal return
Returns
error return
A0 has one of the following values:
04
012
022
Illegal pointer link
L,U A0,address-of-FCT
L,U A1,address-of-deletepacket
I$BJ X11,CBxxID$
error return or no find
return
normal return
Registers returned when A0 = 04:
A1 = address of delete packet
A2 = 0 or previous sequence number containing bad link
A3 = address of table descriptor
A4 = 0 or link identifier (1=pointer, 2=type, 3=version)
A5 = sequence number out of range
FTI not in main storage
Designated table not in main storage
7700000000xx
I/O error, where xx is the I/O status returned
L,U A0,address-of-FCT
L,U A1,address-of-deletepacket
LMJ X11,xxID$
error return or no find
return
normal return
It may be necessary to write the requested table back to mass storage (WPFxxT$)
and write the FTI (WFTI$) to appropriately update the file for changes that were
successfully made before the error occurred. Otherwise the file is left in a partially
corrupted state.
7833 1733–004 5–15

BSP$-Program File Basic Service Package
no find return
A0 has one of the following values:
001
011
021
041
Pointer table
Pointer
A1 = 0
Type Link
Version link
A2 = sequence number of last item referenced
normal return
Requested item has been deleted from table.
A0 = pointer to item marked as deleted
A1 = sequence number of item marked as deleted
A2 = link type (H1) and sequence number of item pointing to this item (H2)
Packet Formats for Table Item Delete
• Element Table Item
0 11 12 17 18 35
0 element name
1
2 zeros
3 zeros zeros type zeros
4 version name or blank
5
Note: Element type 1 may be used for deleting procedures of types 2, 3, or 4.
5–16 7833 1733–004

BSP$-Program File Basic Service Package
• Assembler, FORTRAN, or PLUS Procedure Table Item Delete Packet
0 35
0 procedure name
1
3 zeros
4 zeros
• COBOL Procedure Table Item Delete Packet
0 1 35
0 COBOL procedure name (first 12 characters)
1
2 zeros
3 0 C
I
4 COBOL procedure name (second 12 characters)
5
6 zeros
7 COBOL procedure name (last six characters)
Note: The first 4 words are included in every CPT Delete Packet. The second 4 words
are included only if the procedure name exceeds 12 characters, and bit 1 of word 3
(Continuation Indicator) is set.
• Entry Point Table Item Delete Packet
0 35
0 entry point name
1
2 zeros
3 zeros
7833 1733–004 5–17

BSP$-Program File Basic Service Package
5.1.5. Entry Look-Up by Number
The BSP$ entry points for looking up program file items by sequence number are
(CB)ETNL$ Element Table Number Look-up
(CB)APTNL$ Assembler Procedure Table Number Look-up
(CB)CPTNL$ COBOL Procedure Table Number Look-up
(CB)FPTNL$ FORTRAN Procedure Table Number Look-up
(CB)EPTNL$ Relocatable Element Entry Point Table Number Look-up
Calling Sequence
Auto Switch
L,U A0,address-of-FCT
L,U A1,sequence-number
LMJ X11,CBxxNL$-1
error return
normal return
Returns
error return
A0 has one of the following values:
04
012
014
022
Sequence number not in table
FTI not in main storage
Common Bank or
Relocatable
L,U A0,address-of-FCT
L,U A1,sequence-number
I$BJ X11,CBxxNL$
error return
normal return
Sequence number is out of range
Table not in main storage
7700000000xx
I/O error, where xx is the I/O status returned
Relocatable
L,,U A0,address-of-FCT
L,U A1,sequence-number
LMJ X11,xxNL$
error return
normal return
5–18 7833 1733–004

A1 = sequence number
A2 = number of entries in table
normal return
BSP$-Program File Basic Service Package
A0 = Location of item in buffer (that table was previously read into using RPFxxT$).
For the CPTNL$ entry point, this is the location of the 4-word block indicated by the
sequence number supplied by the caller.
The COBOL procedure table item may be 4 words or 8 words in length. However,
BSP$ returns the pointer to a 4-word block in register A0. Therefore, the
continuation indicator (bit 1, offset 3 of the item) may be checked to determine the
size of the item. A suggested method of searching the COBOL procedure table is
shown in the following example.
7833 1733–004 5–19

BSP$-Program File Basic Service Package
Example of Using CPTNL$
The following example uses CPTNL$ to search the COBOL procedure table:
$INCLUDE 'MAXR$' .
$(0) .
FCT $RES 34 . File control table
CPTBL $RES 252 . Buffer for COBOL procedure table
FILENAME ‘FILE ‘ . Program file name
CPTNUM $EQUF,H2 0213,X1 . Number of 4 word blocks
$(1) .
START .
DL A6,FILENAME . Get file name
DS A6,FCT . Put it in first two words of FCT
L,U A0,FCT . Get address of FCT
LMJ X11,RFTI$ . Read FTI
J BSPERR . Error return
.
L,U A0,FCT . Get address of FCT
L A1,(CPTBL,252) . Get address, length of buffer
LMJ X11,RPFCPT$ . Read COBOL procedure table
J BSPERR . Error return
.
L,U X1,CPTBL . Get address of buffer for CPTNUM
LA,U A7,0 . Initialize loop counter to zero
LOOP .
L,U A0,FCT . Get address of FCT
AA,U A7,1 . Increment loop counter
L A1,A7 . Set sequence number
LMJ X11,CPTNL$ . Get COBOL item for sequence number
J BSPERR . Error return
.
L,S1 A3,3,A0 . Get continuation indicator bit
TOP,U A3,020 . Is it set?
J 4WORDITEM . No, handle 4 word item
AA,U A7,1 . 8 word item, increment loop counter
. to skip reading next 4-word block
. .
. . handle 8-word item
. .
J CHKLOOP . Check for loop termination
4WORDITEM .
. .
. . handle 4-word item
. .
CHKLOOP . Loop termination code
TE A7,CPTNUM . Last 4-word block reached?
J LOOP . No, keep reading
. .
. .
. .
5–20 7833 1733–004

5.1.6. Change Item in Requested Table
BSP$-Program File Basic Service Package
The entry points to change an item in one of the program file tables are the following
[CB]ETIC$ Change Element Table Item
[CB]APTIC$ Change Assembler Procedure Table Item
[CB]CPTIC$ Change COBOL Procedure Table Item
[CB]FPTIC$ Change FORTRAN/PLUS Procedure Table Item
[CB]EPTIC$ Change Relocatable Element Entry Point Table Item
Calling Sequence
Auto Switch
L,U A0,address-of-FCT
L,U A1,address-of-searchpacket
L,U A2,address-of-new-item
LMJ X11,CBxxIC$-1
error or no find return
normal return
Common Bank or
Relocatable
L,U A0,address-of-FCT
L,U A1,address-of-searchpacket
L,U A2,address-of-new-item
I$BJ X11,CBxxIC$
error or no find return
normal return
Relocatable
L,U A0,address-of-FCT
L,U A1,address-of-searchpacket
L,U A2,address-of-new-item
LMJ X11,xxIC$
error or no find return
normal return
The formats for the Table Item Search Packet are described in 5.1.3, “Search Table for
Requested Item.” The name in this packet is the name of the item to be changed. If an
Element Table Item is to be changed then the element type and version name (if any)
must also be specified. The address of the Table Item Search Packet must be in register
A1.
The formats for the new Table Item are described in 5.1.7, “Add Item to Requested
Table.” The address of the new Table Item must be in register A2.
The new Table Item (address in register A2) will replace the Table Item specified by the
search packet (address in register A1).
Returns
error return (0,X11)
A0 has one of the following values:
004
012
Illegal pointer link
No FTI
7833 1733–004 5–21

BSP$-Program File Basic Service Package
022
045
Designated table not in main storage buffer
New item is different size than search item
07700000000xx
I/O error, xx is I/O status code
It may be necessary to write the requested table back to mass storage (WPFxxT$)
and write the FTI (WFTI$) to appropriately update the file for changes that were
successfully made before the error occurred. Otherwise the file is left in a partially
corrupted state.
no-find return (0,X11)
A0 has one of the following values:
001
011
021
041
Pointer table
Pointer link
Type link
Version link
normal return (1,X11)
A0
A1
A2
Location of changed item in buffer that table was previously read into using
Read Program File Table (RFPxxT$) function
Sequence number of changed item
Sequence number of duplicate item that was deleted (if any)
5–22 7833 1733–004

5.1.7. Add Item to Requested Table
BSP$-Program File Basic Service Package
The BSP$ entry points for adding items to program file tables are
(CB)ETIA$ Element Table Item Add
(CB)APTIA$ Assembler Procedure Table Item Add
(CB)CPTIA$ COBOL Procedure Table Item Add
(CB)FPTIA$ FORTRAN/PLUS Procedure Table Item Add
(CB)EPTIA$ Relocatable Entry Point Table Item Add
Calling Sequence
Auto Switch
L,U A0,address-of-FCT
L,U A1,address-of-addpacket
LMJ X11,CBxxIC$-1
error or no find return
normal return
Returns
error return
A0 has one of the following values:
04
Illegal pointer link
Registers returned when A0 = 04:
012
022
Common Bank or
Relocatable
L,U A0,address-of-FCT
L,U A1,address-of-addpacket
I$BJ X11,CBxxIC$
error return
normal return
A1 = address of packet (search, add, or delete)
A2 = 0 or previous sequence number containing bad link
A3 = address of table descriptor
A4 = 0 or link identifier (1=pointer, 2=type, 3=version)
A5 = sequence number out of range
FTI not in main storage
Designated table not in main storage
Relocatable
L,U A0,address-of-FCT
L,U A1,address-of-addpacket
LMJ X11,xxIC$
error return
normal return
7833 1733–004 5–23

BSP$-Program File Basic Service Package
044
046
047
No room for item
Illegal element type of 1 (subtype 035 only), 2, 3, 4, 5, or 6 for LEPF
Illegal element text length granularity value for LEPF
7700000000xx
I/O error, where xx is the I/O status retured
It may be necessary to write the requested table back to mass storage (WPFxxT$)
and write the FTI (WFTI$) to appropriately update the file for changes that were
successfully made before the error occurred. Otherwise the file is left in a partially
corrupted state.
normal return
Requested item has been added to designated table.
A0 = address in buffer of item added
A1 = new sequence number
A2 = sequence number of duplicate element or 0
If the item being added duplicates an existing item, the existing item is automatically
marked as deleted by BSP$.
If the item being added is for the Element Table (ETIA$ function), the following items
should be noted:
• If the first word of the version name in the packet (word 4) is zeroes, blanks will be
used for the entire version name (words 4 and 5).
• If time and date in the packet (word 9) are zeroes, the current time and date will be
used.
• If this program file is a PF or LPF (RFTI$ or RFTI$$ normal return with A1, bit 29
clear; see 5.1.1), the element may have at most 262,143 sectors of element text.
• If this program file is an LEPF (RFTI$$ normal return with A1, bit 29 set) the element
may have over 262,143 sectors of element text. Additional LEPF considerations are
contained in this section under the packet descriptions for symbolic and omnibus
elements and in 5.3.
• If this program file is an LEPF, procedure elements (element type 1, subtype 035 and
element types 2, 3, and 4), relocatable elements (element type 5), and executable
elements (element type 6) may not be added to the PF.
5–24 7833 1733–004

BSP$-Program File Basic Service Package
• The calling program is responsible for updating the FTI next write location in word
FCT+7 (see Figure 5–1).
• If the element being added is a relocatable element, the Relocatable Element Entry
Point Table control information in the FTI is cleared. This removes the table when
the FTI is written back to the program file.
Packet Formats for Table Item Add
• Symbolic or Procedure Element Add to Element Table
0 5 6 11 12 17 18 23 24 29 30 35
0 element name (Fieldata L.J.S.F.)
1
2 zero
3 flag-bits element-type zero
4 version name or blanks (Fieldata L.J.S.F.)
5
6 cycle limit latest cycle number current number of cycles
7 element
subtype
length of element text
8 sector location of element text on mass storage
9 time element added (or zero) date element added (or zero)
Flag-bits (word 3, bits 0 through 11) include the 2-bit element-text-length granularity
field in bits 1 and 2. The meaning of this field depends on one of the following two
program file types:
• For a PF or LPF, this field is not used and should be zero.
• For an LEPF, this field contains the granularity of the length of element-text field
in word 7.
The following may be specified for element-text-length granularity:
0 Element text length is in number of sectors
1 Element text length is in number of tracks. A track contains
64 sectors.
2 Element text length is in number of positions. A position
contains 64 tracks or 4,096 sectors.
7833 1733–004 5–25

BSP$-Program File Basic Service Package
Element type is
01 If Symbolic Element
02 If Assembler Procedure Element
03 If COBOL Procedure Element
04 If FORTRAN Procedure Element.
A procedure element cannot be added to an LEPF.
Element subtype: see 2.4, SSTYP$.
Length of element text (word 7, bits 6 through 35). The meaning of this field
depends on one of the following two program file types:
• For a PF or LPF, bits 6 through 17 of this field are not used and should be zero.
Bits 18 through 35 are the length of the element text in sectors. This allows a
maximum of 0777777 or 262,143 sectors of element text.
• For an LEPF, the meaning of this field depends on the contents of the flag-bits
element-text-length granularity field, as previously described.
• Relocatable Element Add to Element Table
0 11 12 17 18 35
0 element name (Fieldata L.J.S.F.)
1
2 zero
3 flag-bits type = 5 zero
4 version name or blanks (Fieldata L.J.S.F.)
5
6 location of preamble
7 length of preamble length of relocatable text
8 sector location of element text on mass storage
9 time element added (or zero) date element added (or zero)
5–26 7833 1733–004

BSP$-Program File Basic Service Package
The total length in sectors of the element text is the sum for length of preamble and
length of relocatable text.
A relocatable element cannot be added to an LEPF.
• Executable Element Add to Element Table
0 11 12 17 18 35
0 element name (Fieldata L.J.S.F.)
1
2 zero
3 flag-bits type = 6 zero
4 version name or blanks
5
6 bank informataion
7 zero length of element text
8 sector location of element on mass storage
9 time element added (or zero) date element added (or zero)
An executable element cannot be added to an LEPF.
• Omnibus Element Add to Element Table
0 5 6 11 12 17 18 23 24 29 30 35
0 element name (Fieldata L.J.S.F.)
1
2 zero
3 flag-bits type = 7 zero
4 version name or blanks (Fieldata L.J.S.F.)
5
6 Reserved for use by applications
7 element
subtype
element
subsubtype
length of element text
8 sector location of element text on mass storage
9 time element added (or zero) date element added (or zero)
7833 1733–004 5–27

BSP$-Program File Basic Service Package
Flag-bits (word 3, bits 0 through 11) include the 2-bit element-text-length granularity
field in bits 1 and 2. This field is described following the Symbolic or Procedure
Element Add to Element Table packet.
Element subtype (word 7, bits 0 through 5) is described in section 2.4, SSTYP$.
Length of element text (word 7, bits 12 through 35). The meaning of this field
depends on one of the following two program file types:
• For a PF or LPF, bits 12 through 17 of this field are not used and should be zero.
Bits 18 through 35 are the length of the element text in sectors. This allows a
maximum of 0777777 or 262,143 sectors of element text.
• For an LEPF, the meaning of this field depends on the contents of the flag-bits
element-text-length-granularity field, as described following the Symbolic or
Procedure Element Add to Element Table packet.
• Assembler, FORTRAN, or PLUS Procedure Item
0 1 2 3 4 5 6 17 18 35
0 procedure name
1
2 related element table item number zero
3 D
F
0 A S K 0 relative word location of the procedure in the file
• COBOL Procedure Item Add to COBOL Procedure Table
0 1 2 3 4 5 6 17 18 35
0 COBOL procedure name (first 12 characters)
1
2 related element table item number zero
3 D
F
C
I
A S K 0 relative word location of the procedure in the file
4 COBOL procedure name (second 12 characters)
5
6 zeros
7 COBOL procedure name (final six characters)
Note: The first 4 words must be in all COBOL Procedure Table Add Packets.
The second 4 words will be present only if the COBOL procedure name exceeds
12 characters, and bit 1 of word 3 (continuation indicator) is set to 1.
5–28 7833 1733–004

• Entry Point Table Item Add
BSP$-Program File Basic Service Package
0 17 18 35
0 entry point name
1
2 related element table item number zero
3 D
F
5.1.8. Write Last Item Referenced
7833 1733–004 5–29
zeros
The BSP$ entry points for writing out the last item referenced are
(CB)PTEWT$ Part Table Element Table Write
(CB)PTATWT$ Part Table Assembler Procedure Table Write
(CB)PTCTWT$ Part Table COBOL Procedure Table Write
(CB)PTFTWT$ Part Table FORTRAN Procedure Table Write
(CB)PTETWT$ Part Table Entry Point Table Write
Calling Sequence
Auto Switch
L,U A0,address-of-FCT
LMJ X11,CBPTxxWT$-1
Returns
error return
error return
normal return
A0 has one of the following values:
7700000000xx
012
Common Bank or
Relocatable
L,U A0,address-of-FCT
I$BJ X11,CBPTxxWT$
error return
normal return
I/O error, where xx is the I/O status returned
No FTI
Relocatable
L,U A0,address-of-FCT
LMJ X11,PTxxWT$
error return
normal return

BSP$-Program File Basic Service Package
022
024
Table not in main storage. Caller must have first done an RPFxxT$ call.
User error
normal return
Last item referenced written.
This function should be called only if the previous BSP$ functions: search table (xxIS$),
delete item (xxIS$), entry look-up (xxNL$), change item (xxIC$), or add item (xxIA$)
resulted in a normal return. In each case, register A0 has the address of the table item
processed by the function. The PTxxWT$ function will write the 1 or 2 sectors (28 or 56
words) that contain the table item to mass storage. Note the following about this
function:
• It is not necessary to call this function after the delete item, change item, or add
item functions. The modified item will be written to mass storage either before
BSP$ reads the next buffer or when the WPFxx$ function is called.
• This function should be called only if it is determined that the table item must be
written to mass storage immediately.
• This function is very inefficient, particularly if many table items need to be written,
for the following reasons:
− Writing small buffers of 1 or 2 sectors incurs a large amount of overhead.
− Because each table item is only a partial sector, each sector may need to be
written multiple times. For the element table, each sector is written an average
of 3.6 times. For the other program file tables, each sector is written an average
of 7 times.
• The mark item as updated (xxIS$) function (see 5.1.9) should be considered as a
more efficient alternative to this function.
5.1.9. Mark Item as Updated
The BSP$ entry points for marking the last program file table item referenced as having
been updated are:
(CB)ETIU$ Element Table Item Updated
(CB)APTIU$ Assembler Procedure Table Item Updated
(CB)CPTIU$ COBOL Procedure Table Item Updated
(CB)FPTIU$ FORTRAN/PLUS Procedure Table Item Updated
(CB)EPTIU$ Relocatable Element Entry Point Item Updated
5–30 7833 1733–004

Calling Sequence
Auto Switch
L,U A0,address-of-FCT
LMJ X11,CBxxIU$-1
Returns
error return
error return
normal return
A0 has one of the following values:
012
022
normal return
FTI not in main storage.
BSP$-Program File Basic Service Package
Common Bank or
Relocatable
L,U A0,address-of-FCT
I$BJ X11,CBxxIU$
Designated table not in main storage.
error return
normal return
Relocatable
L,U A0,address-of-FCT
LMJ X11,xxIU$
error return
normal return
The last program file table item referenced is marked as having been updated. The
table item will be written to mass storage, either before BSP$ reads the next buffer
or when the WPFxx$ function is called.
This function should be called only if the previous BSP$ search table (xxIS$) or look-up
(xxNL$) function resulted in a normal return and if the caller subsequently modified the
table item pointed to by register A0. The following should be noted about this function:
• It is not necessary to call this function after the delete item (xxID$), change item
(xxIC$) or add item (xxIA$) functions. The table item is already marked as updated
by these functions.
• This function is efficient, since it does not perform any I/O.
• The write last item referenced (PTxxWT$) function described in 5.1.8 should be used
if it determined that the table item must be written to mass storage immediately.
7833 1733–004 5–31

BSP$-Program File Basic Service Package
5.1.10. Write Requested Table Back to Mass Storage
The BSP$ entry points for writing program file tables back to the file are
(CB)WPFET$ Write Program File Element Table
(CB)WPFAPT$ Write Program File Assembler Procedure Table
(CB)WPFCPT$ Write Program File COBOL Procedure Table
(CB)WPFFPT$ Write Program File FORTRAN Procedure Table
(CB)WPFEPT$ Write Program File Entry Point Table
Calling Sequence
Auto Switch
L,U A0,address-of-FCT
LMJ X11,CBWPFxx$-1
error return
normal return
Returns
error return
A0 has one of the following values:
012
022
FTI not in main storage
Common Bank or
Relocatable
L,U A0,address-of-FCT
I$BJ X11,CBWPFxx$
error return
normal return
Relocatable
L,U A0,address-of-FCT
LMJ X11,WPFxx$
error return
normal return
Requested table not in main storage. Caller must have first done an RPFxxT$
call.
7700000000xx
normal return
I/O error, where xx is the I/O status returned.
Designated Table, Pointer Table, and last segment left in main storage, if changed,
are written to mass storage.
5–32 7833 1733–004

5.1.11. Write FTI
Write the FTI back to the program file.
Calling Sequence
Auto Switch
L,U A0,address-of-FCT
LMJ X11,CBWFTI$-1
error return
normal return
Returns
error return
A0 has one of the following values:
042
043
BSP$-Program File Basic Service Package
Common Bank or
Relocatable
L,U A0,address-of-FCT
I$BJ X11,CBWFTI$
error return
normal return
Relocatable
L,U A0,address-of-FCT
LMJ X11,WFTI$
error return
normal return
At least one table has not been written back by a call on Write Program File
Table.
Invalid next sector for text
7700000000xx
normal return
I/O Error, where xx is the I/O status code returned.
The FTI has been written back to mass storage.
7833 1733–004 5–33

BSP$-Program File Basic Service Package
5.2. Example of Using BSP$
The following example uses BSP$ to access a program file:
$(2)
FCT $RES 43 . File control table
ELTTBL $RES 252 . Buffer for element table
FILENAME ‘TESTFILE ‘ . Program file name
ADDPKT . BSP$ add packet
‘NEWPROGRAM ‘ . Element name
+ 0 . Word 2 of add packet
+ 1,0 . Element type (symbolic)
‘VERS-3 ‘ . Element version name
+ 5,0,1 . Element cycle information
+ ELTLEN . Sector length of element text
+ ELTADRR . Address of element text (sector)
+ 0 . Time and date element added
. (filled by BSP$)
.
.
.
$(1)
DL A6,FILENAME . Get file name
DS A6,FCT . Put in top of FCT
L,U A0,FCT . Get address of FCT
LMJ X11,RFTI$ . Read FTI
J BSPERR . Error return
.
L,U A0,FCT . Get address of FCT
L A1,(ELTTBL,252) . Get addr,len of buffer
LMJ X11,RPFET$ . Read element table into buffer
J BSPERR . Error return
.
L,U A0,FCT . Get address of FCT
L,U A1,ADDPKT . Get address of add packet
LMJ X11,ETIA$ . Add the element to the file
J BSPERR . Error return
.
. Write element text, using SDFO (for example)
.
L,U A0,FCT . Get address of FCT
LMJ X11,WPFET$ . Write back the element table
J BSPERR . Error return
L A7,FCT+7 . Get next write location
A,U A7,ELTLEN . Add length of new element
S A7,FCT+7 . Put in FCT
.
L,U A0,FCT . Get address of FCT
LMJ X11,WFTI$ . Write back the
J BSPERR . Error return
.
.
.
5–34 7833 1733–004

BSP$-Program File Basic Service Package
In this example, BSP$ adds an element to a program file. The following two buffers and
one packet are required:
• FCT is for the file control table
• ELTTBL is for the program file element table
• ADDPKT is for a packet that holds information about the element to be added
The first call to BSP$ reads the file control table. The file control table must be read
before any other calls are made to BSP$.
The next call to BSP$ is to read the program file element table. This table must be read
before elements are added, deleted or searched for.
The BSP$ call to ETIA$ adds the element described in the add packet ADDPKT to the
contents in the file TESTFILE. The element name is NEWPROGRAM with version name
VERS-3. It is a symbolic element, cycle 0, with a maximum cycle limit of 5.
ELTLEN is the sector length of the element. ELTADDR is the starting sector address of
the element in the file TESTFILE. The calling program must write the actual text of the
element to the file using the SDFO routine.
When the element is added to the program file element table, the table must be written
back to WPFET$. The next write location is updated by adding the element sector
length to word 7 of the FCT. A call to WFTI$ writes the updated FTI back to the file.
This completes updating of the file.
5.3. LEPF Considerations
This section contains additional information, limitations, restrictions, and considerations
pertaining to LEPFs and their use.
The following are general limitations and restrictions:
• LEPFs are first supported by the BSP$ contained in SYSLIB level 76R1. LEPFs are
not recognized as program files by any prior SYSLIB level.
• The initial implementation of LEPFs is intended primarily for use by MAPPER, as a
container for large MAPPER reports (symbolic elements) that have over 262,143
sectors of element text.
• Initially, only MAPPER, FURPUR, PCFP, and BSP$ support LEPFs.
• Initially, LEPFs are not supported by the Exec, including the ER PFx$ interface and
the command line interface (@ADD, @START, @XQT, and so on).
• Initially, LEPFs cannot contain procedure elements (element type 1, subtype 035,
and element types 2, 3, and 4), relocatable elements (element type 5), and
executable elements (element type 6).
• Calling programs that are not modified will not recognize LEPFs as program files.
This includes programs that call the relocatable version of BSP$, even when they are
re-collected with SYSLIB level 76R1 or higher.
7833 1733–004 5–35

BSP$-Program File Basic Service Package
The following are considerations when reading or initializing the program file FTI with the
RFTI$ or RFTI$$ functions (see 5.1.1):
• Calling programs that use the RFTI$ function will not recognize existing LEPFs and
cannot initialize an empty file as an LEPF. These programs must be modified to use
the RFTI$$ function to read the FTI.
• Calling programs that use the RFTI$$ function must be modified to specify the new
parameter, BSP$ interface level, in register A1, H1. A value of 1 is required to
recognize existing LEPFs and to initialize an empty file as an LEPF.
• The parameter specified in register A2 is ignored if the file is an existing program file.
• On a normal return, the value in register A1 describes the basic program file
characteristics of the file that was read or initialized. Bit 29 of A1 is clear if this file is
a PF or LPF; bit 29 of A1 is set if this file is an LEPF. The calling program should
save the A1 return value so that the contents of existing element table entries can
be correctly interpreted and so that new element table entries can be correctly
formatted.
To correctly interpret the length of element text when reading element table entries with
the ETIS$ function (see 5.1.3) or the ETNL$ function (see 5.1.5), the following need to be
considered:
• When reading elements from a PF or LPF:
− The maximum element text size is 262,143 sectors.
− The element text length in word 7 is stated in sectors for all element types.
− For all element types, the flag bits field, element-text-length granularity (word 3,
bits 1 and 2) is not used and should be ignored.
− For symbolic elements, element-text-length word 7, bits 6 through 17 (S2 and
S3) are not used and should be ignored.
− For omnibus elements, element-text-length word 7, bits 12 through 17 (S3) are
not used and should be ignored.
• When reading elements from an LEPF:
− The maximum element text size is limited only by maximum file size. The
theoretical maximum is 07777764400 or 1,073,735,936 sectors. This is based
on the maximum possible file size minus 1,792 sectors reserved for the TOC of
a standard LEPF.
− Make sure the correct field size is used when loading element-text length from
word 7. For symbolic elements the field size is 30 bits (bits 6 through 35) and
for omnibus elements the field size is 24 bits (bits 12 through 35).
− Once the correct element-text-length value is loaded, the element-text-length
granularity field (word 3, bits 1 and 2) must be examined:
ο If it is 0, element text length is stated in sectors.
ο If it is 1, element text length is stated in tracks. Track granularity can be
converted to sector granularity by multiplying by 64 or by shifting left by 6
bits.
5–36 7833 1733–004

BSP$-Program File Basic Service Package
ο If it is 2, element text length is stated in positions. Position granularity can
be converted to sector granularity by multiplying by 4,096 or by shifting left
by 12 bits.
ο Combinations of element text length and element text length granularity can
result in a number of sectors that are over the theoretical maximum
described above. The result may even be over 36 bits, so maximum value
checks or double-word operations are recommended to determine the
validity of the calculated element text length.
The following are considerations when creating element table entries with the ETIA$
function (see 5.1.7):
• When creating elements in a PF or LPF:
− The maximum element text size is 262,143 sectors.
− The element-text-length granularity (word 3, bits 1 and 2) field should be 0.
− For symbolic elements, element-text-length word 7, bits 6 through 17 (S2 and
S3) should be 0.
− For omnibus elements, element-text-length word 7, bits 12 through 17 (S3)
should be 0.
• When creating elements in an LEPF:
− If the element text is at most 262,143 sectors, use the previous PF and LPF
format for the element table item.
− For efficiency and to avoid wasted mass storage, select the smallest granularity
possible. Sector granularity is the smallest, followed by track and then position.
ο For symbolic elements, the 30-bit element-text-length field is large enough
to describe any element text using sector granularity. Neither track nor
position granularity is needed for symbolic elements.
ο For omnibus elements, the 24-bit element-text-length field is large enough to
describe element text of 16,777,152 sectors using sector granularity. For
element text larger that this, use track granularity. Position granularity is not
needed for omnibus elements.
− When using track or position granularity, make sure that element text length is
rounded up to the next granule, if necessary. For example, 5,000 tracks plus 1
sector (320,001 sectors) must be rounded up to 5,001 tracks (320,064 sectors);
70 positions plus 1 sector (286,721 sectors) must be rounded up to 71 positions
(290,816 sectors).
− If element text length is rounded up, as described above, additional sectors must
be written to pad the element to the proper granule boundary. It is
recommended that sectors containing zeroes be used for the padding. In the
previous examples, the track granularity element would require 63 sectors of
padding and the position granularity element would require 4,095 sectors of
padding.
− When using track or position granularity, make sure that the final element text
length is converted back to number of sectors when updating the FTI next write
location in word FCT+7 (see Figure 5–1).
7833 1733–004 5–37

BSP$-Program File Basic Service Package
5–38 7833 1733–004

Section 6
CABSAD$, CRELAD$–Addressing
Routines
The CABSAD$ routine computes the absolute address for a given address relative to a
location counter. CRELAD$ computes the element name, location counter number, and
address relative to the location number of a caller-specified absolute address.
The following routines are available either as relocatables or common bank absolutes and
can be used in conjunction with D-bank segments above 65K addressing.
When calling the common bank version of the routines, it is necessary to provide a
300-word buffer for their internal use.
6.1. Absolute Addressing Routines
The CABSAD$ routines are called by the MASM procedure C$ABSAD. C$ABSAD is
used to generate the calling sequence for the relocatable version, the common bank
version, or the common bank version using the Auto Switch calling sequence. Section 3
describes the advantages and disadvantages of using the different types of calls.
Calling Format
C$ABSAD[,t] func-code [,p1,p2,p3] [pkt-addr]
error return
normal return
Parameters
t
Type of call to the routine. This parameter is optional and may be omitted. CB or A,
if specified, must be enclosed by apostrophes.
blank Call the relocatable version. This is the default if t is omitted.
'CB' Call the common bank version.
'A' Call the common bank version using the Auto Switch method.
7833 1733–004 6–1

CABSAD$, CRELAD$–Addressing Routines
func-code
The function code determines which of the absolute addressing routines is called by
C$ABSAD. The function codes are described in the sections explaining each of the
functions. The function code must be enclosed by apostrophes.
The only values allowed for the function code on the C$ABSAD procedure call are
CABSAD$, CAINIT$, CBX$, CSX$, and CSYMVL$. Any other value entered for the
function code parameter on the C$ABSAD procedure call causes MASM to generate
an E flag on that line and print the error message.
p1,p2,p3
ILLEGAL C$ABSAD FUNCTION
The use of these parameters depends on the particular routine being called by
C$ABSAD. Some of the routines use only p1; some may use only p1 and p2. In
general, these parameters may be omitted. If so, the calling procedure uses the
values in specific registers for the values of these parameters. Each routine's
subsection describes these parameters.
pkt-addr
Address of the 300-word packet required by the common bank version of the
routines. If this parameter is omitted and the common bank version of the routine is
called (parameter t set to 'A' or 'CB'), then the address in register A5 is used as the
starting address of the packet. This parameter may be omitted if the call is to the
relocatable version of the routines but including it does not cause any problems.
6.1.1. CABSAD$–Compute Absolute Address
CABSAD$ computes the absolute address for a given address relative to a location
counter.
Calling Format
C$ABSAD[,t] ‘CABSAD$’[,rel-addr,lc,elt-name] [pkt-addr]
error return
normal return
Parameters
t
See 6.1.
CABSAD$
CABSAD$ is the function code that determines which of the absolute addressing
routines is called by C$ABSAD. It must be enclosed by apostrophes.
6–2 7833 1733–004

el-addr
lc
CABSAD$, CRELAD$–Addressing Routines
Relative address to be converted. This is the address relative to some location
counter that is converted to an absolute address.
Location counter of the address to be converted. Parameter rel-addr gives the
address to be converted relative to a specific location counter. This parameter tells
the routine which location counter to use. This parameter may be given as an actual
number, a tag that has been equated to an actual number, or the address of a word
that contains the number.
elt-name
Name of the element containing the relocatable address that is to be converted to an
absolute address. The element name may be from 1 to 12 characters selected from
the set A through Z, 0 through 9, and the special characters - and $. If given as a
string, then the parameter must be surrounded by apostrophes on the procedure
call. This parameter can also be given as the address of a two-word area that
contains the name in Fieldata format, left-justified and space-filled.
pkt-addr
See 6.1.
If all of the parameters rel-addr,lc,elt-name are omitted on the call, then the routine uses
the value in register A0 for rel-addr, the value in register A1 for lc, and the value in
registers A2 and A3 for elt-name.
Returns
normal
Register A0 contains the requested absolute address and A1 contains a pointer to
the Segment Load Table (SLT$). If register A1 = 0, either the program is not
segmented or the element lies in the main segment. The absolute address returned
in A0 is always in main storage.
The following instruction causes the instruction immediately after it to be skipped if
the element is in main storage:
TP SLT$,A1
On return, H1 of register A2 contains the length of the specified location counter and
H2 of register A2 contains the starting address of that location counter, for possible
further use.
7833 1733–004 6–3

CABSAD$, CRELAD$–Addressing Routines
error
A0 < 0
A0 > 0
The requested address does not exist. Possible reasons include:
• The executing program does not have this element
• The element has no such location counter
• The location is out of range for that location counter
• The program was collected with the Z option, so there are no diagnostic
tables. See the Collector Programming Reference Manual
• The element is not an absolute element
A0 has an I/O error status code, and register A1 contains the sector address of
the error on mass storage in the file from which the program is loaded.
Reinitializing CABSAD$
If a program using CABSAD$ is checkpointed and restarted, the restart contingency
routine should contain the following instruction to reinitialize the CABSAD$ tables:
SZ *CABSAD$-1
6.1.2. CAINIT$–Initialize CABSAD$
CAINIT$ initializes CABSAD$ to examine the diagnostic tables of an absolute element
other than the one being executed.
CAINIT$ initializes the tables in CABSAD$. The tables point to the diagnostic tables of
an absolute element that is indicated by the file name and header table start address.
Until reinitialized, all references to CABSAD$, CSX$, CBX$, and CSYMVL$ refer to the
specified absolute element. References to the Segment Load Table (SLT$) are not valid
unless CABSAD$ is working on the absolute element that is executing.
Calling Format
C$ABSAD[,t] ‘CAINIT$’[,file-name,sector-addr] [pkt-addr]
error return
normal return
Parameters
t
See 6.1.
6–4 7833 1733–004

CAINIT$
CABSAD$, CRELAD$–Addressing Routines
CAINIT$ is the function code that determines which of the absolute addressing
routines is called by C$ABSAD. It must be enclosed by apostrophes.
file-name
Internal name of the file containing the absolute element that the calling program
wishes to examine. The file name may be from 1 to 12 characters selected from the
set A through Z, 0 through 9, and the special characters - and $. If given as a string,
then the parameter must be surrounded by apostrophes on the procedure call. This
parameter may also be given as the address of a two-word area that contains the
name in Fieldata format, left-justified and space-filled.
sector-addr
Sector location of the absolute element in the file named by parameter file-name.
This parameter may be given as an actual number, a tag that has been equated to an
actual number or the address of a word that contains value that is to be used as the
sector address.
pkt-addr
See 6.1.
If both of the parameters file-name and sector-addr are omitted on the call, then the
routine uses the value in the register pair A0 and A1 for file-name and the value in
register A2 for sector-addr.
Error Return
The error return is identical to a CABSAD$ error return.
6.1.3. CBX$–Compute Bank Descriptor Index
CBX$ computes the bank descriptor index (BDI) that corresponds to a given bank name.
Calling Format
C$ABSAD[,t] ‘CBX$’[,bank-name] [pkt-addr]
error return
normal return
Parameters
t
See 6.1.
7833 1733–004 6–5

CABSAD$, CRELAD$–Addressing Routines
CBX$
CBX$ is the function code that determines which of the absolute addressing routines
are called by C$ABSAD. It must be enclosed by apostrophes.
bank-name
Name of the bank for which the routine should find the BDI. The bank name may be
from 1 to 12 characters selected from the set A through Z, 0 through 9, and the
special characters - and $. If given as a string, then the parameter must be
surrounded by apostrophes on the procedure call. This parameter may also be given
as the address of a two-word area that contains the name in Fieldata format, leftjustified
and space-filled.
If the parameter bank-name is omitted, then the routine uses the value in registers
A0 and A1 for bank-name. In this case the bank name must be left justified in the
register pair and space filled. The name must be in Fieldata format.
pkt-addr
See 6.1.
Returns
error
normal
A0 = 0
A0 > 0
The system could not find the specified name in the diagnostic table.
An I/O error occurred. The register contents are the same as for an I/O error
from CABSAD$.
Register A0 contains the requested BDI.
6.1.4. CSX$–Compute Segment Index
CSX$ computes the segment index that corresponds to a given segment name.
The calling program can convert a segment index to a Segment Load Table (SLT$) offset
pointer by multiplying the index by 4. Segment indexes are the values that reference ER
LOAD$. The main segment is an exception.
Calling Format
C$ABSAD[,t] ‘CSX$’[,seg-name] [pkt-addr]
error return
normal return
6–6 7833 1733–004

Parameters
t
CSX$
See 6.1.
CABSAD$, CRELAD$–Addressing Routines
CSX$ is the function code that determines which of the absolute addressing routines
are called by C$ABSAD. It must be enclosed by apostrophes.
seg-name
Name of the segment for which the routine should find the segment index. The
segment name may be from 1 to 12 characters selected from the set A through Z, 0
through 9, and the special characters - and $. If given as a string, then the parameter
must be surrounded by apostrophes on the procedure call. This parameter may also
be given as the address of a two-word area that contains the name in Fieldata
format, left-justified and space-filled.
pkt-addr
See 6.1.
If the parameter seg-name is omitted, then the routine uses the value in registers A0 and
A1 for seg-name. In this case, the bank name must be left-justified in the register pair
and space-filled. The name must be in Fieldata format.
Returns
error
normal
The error conditions are the same as for CBX$.
Register A0 contains the requested segment index.
6.1.5. CSYMVL$–Compute Symbol Value
CSYMVL$ computes the value of an externally defined global symbol.
Calling Format
C$ABSAD[,t] ‘CSYMVL$’[,symbol] [pkt-addr]
error return
normal return
Parameters
t
See 6.1.
7833 1733–004 6–7

CABSAD$, CRELAD$–Addressing Routines
CSYMVL$
CSYMVL$ is the function code that determines which of the absolute addressing
routines are called by C$ABSAD. It must be enclosed by apostrophes.
symbol
Name of the symbol for which the routine computes a value. The symbol name may
be from 1 to 12 characters selected from the set A through Z, 0 through 9, and the
special character $. If given as a string, then the parameter must be surrounded by
apostrophes on the procedure call. This parameter may also be given as the address
of a two-word area that contains the name in Fieldata format, left-justified and spacefilled.
If the parameter symbol is omitted, then the routine uses the value in registers A0
and A1 for symbol. In this case, the name must be left-justified in the register pair
and space-filled. The name must be in Fieldata format.
pkt-addr
See 6.1.
Returns
error
normal
Error conditions are the same as those for CBX$.
Register A0 contains the value of the symbol, and register A1 contains a Segment
Load Table (SLT$) pointer (as discussed for CABSAD$). If the symbol is absolute,
register A1 is always zero. If the collection source uses the TYPE EXTDIAG
statement, any externally defined symbol of the collection may be looked up.
Otherwise, unreferenced symbols and symbols defined in SYS$*RLIB$ elements are
excluded. If the symbol is not global, in other words, if it is defined instead by a
locally included element, one of the local definitions is returned. The definition that
is returned cannot be predicted.
6.2. Relocatable Addressing Routines
The CRELAD$ routines are called by the MASM procedure C$RELAD. C$RELAD is used
to generate the calling sequence for the relocatable version, the common bank version,
or the common bank version using the Auto Switch calling sequence. Section 3
describes the advantages and disadvantages of using the different types of calls.
Calling Format
C$RELAD[,t] func-code [,p1,p2] [pkt-addr]
error return
normal return
6–8 7833 1733–004

Parameters
t
CABSAD$, CRELAD$–Addressing Routines
Type of call to the routine. This parameter is optional and may be omitted. CB or A,
if specified, must be enclosed by apostrophes.
func-code
p1,p2
blank Call the relocatable version. This is the default if t is omitted.
'CB' Call the common bank version.
'A' Call the common bank version using the Auto Switch method.
The function code determines which of the absolute addressing routines are called
by C$RELAD. The function codes are described in the sections explaining each of
the functions. The function code must be enclosed by apostrophes.
The only values allowed for the function code on the C$RELAD procedure call are
CRELAD$, CRINIT$, CBN$, and CSN$. Any other value entered for the function
code parameter on the C$RELAD procedure call causes MASM to generate an E flag
on that line and print the error message
ILLEGAL C$RELAD FUNCTION
The description of these parameters depends on the particular routine being called
by C$RELAD. Some of the routines only use p1; some may use both p1 and p2. In
general, these parameters may be omitted. If so, the calling procedure uses the
values in specific registers for the values of these parameters. Each routine's
subsection describes these parameters.
pkt-addr
Address of the 300-word packet required by the common bank version of the
routines. If this parameter is omitted and the common bank version of the routine is
called (parameter t set to 'A' or 'CB'), then the address in register A5 is used as the
starting address of the packet. This parameter may be omitted if the call is to the
relocatable version of the routines, but including it does not cause any problems.
6.2.1. CRELAD$–Compute Relative Address
CRELAD$ computes the element name, location counter number, and address relative
to the location number of a caller-specified absolute address.
Calling Format
C$RELAD[,t] ‘CRELAD$’[,abs-addr] [pkt-addr]
error return
normal return
7833 1733–004 6–9

CABSAD$, CRELAD$–Addressing Routines
Parameters
t
See 6.1.
CRELAD$
CRELAD$ is the function code that determines which of the absolute addressing
routines is called by C$RELAD. It must be enclosed by apostrophes.
abs-addr
Absolute address that is to be converted to a relative address.
If this parameter is omitted, then the routine uses the value in register A0 for
abs-addr.
pkt-addr
See 6.1
Normal Return
If CRELAD$ returns normally, registers A2 and A3 contain an element name that is
left-justified and space-filled. The relative address values corresponding to the input
absolute address are in two registers: register A1 contains a location counter number,
and register A0 contains an address relative to that location counter.
If the input value in register A0 is not in the range of the program, then register A0 is
unchanged, register A1 is set to zero, the register pair A2, A3 is filled with the Fieldata
characters "*ABSOLUTE*", and the normal return is taken. This case also occurs if the
collection of the absolute is done with the Z option on the call to the Collector. When
the Z option is used on the Collector call, the diagnostic tables are not included in the
absolute element produced, and relative addresses cannot be computed.
On normal return, registers A4 and A5 contain the location counter limits or zeros if the
address was absolute. Register A4 equals the location counter lower limit - 1, and A5
equals the location counter upper limit. The following instruction skips the instruction
immediately after it if x contains an address in the same element and location counter
range as the address on the call to CRELAD$ that computed A4 and A5.
TW A4,x
The calling program can save the computation by calling CRELAD$ using registers A1,
A2, and A3 and computing A0 = x-(A4+1).
The routine must be part of the main segment. Only one activity can use CRELAD$ at
one time.
If more than one element in different segments has addresses corresponding to the
given absolute address, the one in main storage is used. If there is no element in main
storage, an error condition exists.
6–10 7833 1733–004

CABSAD$, CRELAD$–Addressing Routines
Error Return
The error return is taken if an I/O status other than 0 or 5 is encountered. In that case,
register A0 contains the status code, register A1 contains the error address on mass
storage, A2 through A3 contain the Fieldata characters "INPUT ERROR", and A4 through
A5 contain zero.
Reinitializing CRELAD$
If a program using CRELAD$ is checkpointed and restarted, CRELAD$ must be
reinitialized. Use the following instruction in the restart contingency code when calling
the relocatable version.
SZ *CRELAD$-1
When calling the common bank version, store zero into the first word of the 300-word
buffer.
SZ buffer-name
The alternate relocatable calling sequence is
L A0,(bdi,addr)
LMJ X11,CRELAD$
error return
normal return
The alternate common bank calling sequence is
L A0,(bdi,addr)
L,U A5,300-word-buffer-starting-address
I$BJ X11,CB$CRELAD$
error return
normal return
This entry and the previous example provide the same results. The only difference is
that a bank descriptor index is specified in H1 of A0. This is necessary if the address in
H2 of register A0 is in an unbased bank or a bank that overlaps the bank containing
CRELAD$ (usually the control bank) and the address is in the overlap area. Otherwise,
when CRELAD$ performs an ER BANK$ to determine the bank descriptor index for the
address, it obtains the wrong BDI because the CRELAD$ bank descriptor register is then
active.
7833 1733–004 6–11

CABSAD$, CRELAD$–Addressing Routines
6.2.2. CRINIT$–Initialize CRELAD$
CRINIT$ initializes CRELAD$ to examine the diagnostic tables of an absolute element
other than the one the system is executing.
This routine initializes the tables of CRELAD$ so that they point to the diagnostic tables
of the absolute element specified by the calling program. All references to CRELAD$,
CSN$, and CBN$ refer to the specified absolute element until they are reinitialized.
References to loaded segments are not meaningful unless CRELAD$ is working on the
absolute element that the system is executing.
Calling Format
C$RELAD[,t] ‘CRINIT$’[,file-name,sector-addr] [pkt-addr]
error return
normal return
Parameters
t
See 6.1
CRINIT$
CRINIT$ is the function code that determines which of the absolute addressing
routines is called by C$RELAD. It must be enclosed by apostrophes.
file-name
Internal name of the file containing the absolute element that the calling program
wishes to examine. The file name may be from 1 to 12 characters selected from the
set A through Z, 0 through 9, and the special characters - and $. If given as a string,
then the parameter must be surrounded by apostrophes on the procedure call. This
parameter may also be given as the address of a two-word area that contains the
name in Fieldata format, left-justified and space-filled.
sector-addr
The sector location of the absolute element in the file named by parameter p1. This
parameter may be given as an actual number, a tag that has been equated to an
actual number or the address of a word that contains a value that is to be used as
the sector address.
6–12 7833 1733–004

pkt-addr
See 6.1
CABSAD$, CRELAD$–Addressing Routines
If both of the parameters file-name and sector-addr are omitted on the call, then the
routine uses the value in registers A0 and A1 for file-name and the value in register A2
for sector-addr.
Error Return
The error return is identical to a CRELAD$ error return.
6.2.3. CBN$–Convert BDI to Symbolic Bank Name
CBN$ determines the symbolic bank name that corresponds to the given BDI and
returns it in registers A0 and A1 in Fieldata format, left-justified, and space-filled.
Calling Format
C$RELAD[,t] ‘CBN$’[,bdi] [pkt-addr]
error return
normal return
Parameters
t
CBN$
bdi
See 6.1.
CBN$ is the function code that determines which of the absolute addressing
routines is called by C$RELAD. It must be enclosed by apostrophes.
bank descriptor index that is to be translated into a bank name. This parameter may
be included as a number, as a tag that has been equated to a number, or as the
address of a word that contains the value of the number.
If parameter bdi is omitted, then the value in register A0 is used as the BDI.
pkt-addr
See 6.1.
Error Return
If A0 = 0 at the error return, the BDI is out of range or refers to a common bank. If A0 ≠
0, an I/O error occurred and the registers contain the same values as for a CRELAD$ I/O
error.
7833 1733–004 6–13

CABSAD$, CRELAD$–Addressing Routines
6.2.4. CSN$–Convert Segment Index to Segment Name
CSN$ determines the symbolic segment name that corresponds to the given segment
index and returns it in registers A0 and A1 in Fieldata format, left-justified, and spacefilled.
Calling Format
C$RELAD[,t] ‘CSN$’[,seg-index] [pkt-addr]
error return
normal return
Parameters
t
CSN$
See 6.1.
CSN$ is the function code that determines which of the absolute addressing
routines is called by C$RELAD. It must be enclosed by apostrophes.
seg-index
Segment index of the segment is to be translated into a segment name. This
parameter may be included as a number, as a tag that has been equated to a
number, or as the address of a word that contains the value of the number.
If the parameter seg-index is omitted, then the value in register A0 is used as the
segment index.
pkt-addr
See 6.1.
Returns
The error and normal returns are the same as for CBN$.
6–14 7833 1733–004

Section 7
CONWRD$–Condition Word Routine
The CONWRD$ routine manipulates bits 7 and 8 of the condition word (bit 0 is the
leftmost bit of the word). These bits indicate whether a task completed successfully or
unsuccessfully, and are defined as follows:
Bit 7 If set, one or more previous tasks had an error.
Bit 8 If set, the most recent task had an error.
See the Exec ER Programming Reference Manual for details on the condition word. The
EXEC extensions to ER SETC$ and @SETC that use bits 7 and 8 of the condition word
are in level 38R2 and higher levels.
CONWRD$ can be called from both MASM or PLUS routines. CONWRD$ is available as
a relocatable element in the SYSLIB file (SYS$LIB$*SYSLIB) or SYS$*RLIB$ and also in
the SYSLIB common bank SYSLIB$1. The relocatable and common bank entry points to
CONWRD$ are listed in Appendix E.
7.1. MASM Interface
CONWRD$ is called with the MASM PROC C$ONWRD. This PROC can call CONWRD$
as a relocatable element, a common bank element, or a common bank element using
the Auto Switch method.
CONWRD$ does not return any parameters or status codes to the caller.
Calling format
C$ONWRD[,t] func
normal return
7833 1733–004 7–1

CONWRD$–Condition Word Routine
Parameters
t
func
The type of call to CONWRD$. This parameter is optional and may be omitted. If CB
or A is specified, it must be enclosed by apostrophes.
blank
'CB'
'A'
Call the relocatable version of CONWRD$. This is the default if t is omitted.
Call the common bank version of CONWRD$.
Call the common banked version of CONWRD$ using the Auto Switch method.
The function for CONWRD$ to perform; it must be enclosed by apostrophes.
'SET27$'
Set bit 8 of the condition word; if bit 8 was already set, then set bit 7.
'CLEAR27$'
Clear bit 8 of the condition word; bit 7 is not changed.
Note: The names SET27 and CLEAR27 may appear to be unusual names for these
functions. The reason for this is that they were named when a different numbering
convention for bit positions was being used. Bit position 27 in the old convention
corresponds to bit position 8 in the current convention.
Example
The following example calls CONWRD$ from a MASM routine.
1. $(1)
2. START
.
.
.
3. C$ONWRD ‘SET27$’ . Set bit 8 of the condition word
.
.
4. C$ONWRD,’CB’ ‘CLEAR27$’ . Clear bit 8
In this example, line 3 calls the relocatable version of CONWRD$ to set bit 8 of the
condition word. Line 4 calls the common bank version of CONWRD$ to clear bit 8 of the
condition word.
7–2 7833 1733–004

7.2. PLUS Interface
CONWRD$–Condition Word Routine
CONWRD$ is called from PLUS routines by declaring procedures with the appropriate
entry points.
Calling Sequence
The following entry points are defined for CONWRD$:
CWSET$
Call the relocatable version of CONWRD$ and set bit 8 of the condition word; if bit 8
is already set, then set bit 7 (bit 0 is the leftmost bit of the word).
CWCLEAR$
Call the relocatable version of CONWRD$ and clear bit 8 of the condition word; bit 7
is not changed.
CBCWSET$
Call the common bank version of CONWRD$ and set bit 8 of the condition word; if
bit 8 is already set, then set bit 7.
CBCWCLEAR$
Call the common bank version of CONWRD$ and clear bit 8 of the condition word;
bit 7 is not changed.
Example
The following example calls CONWRD$ from a PLUS routine:
1. PROCEDURE SET_TASK_ERROR IMPORTED (‘CWSET$’);
2. PROCEDURE CLEAR_TASK_ERROR IMPORTED (‘CBCWCLEAR$’);
.
.
.
3. SET_TASK_ERROR; " Set bit 8 of Condition Word
.
.
4. CLEAR_TASK_ERROR; " Clear bit 8
In this example, line 1 declares a procedure to call the relocatable version of CONWRD$
and set bit 8 of the condition word. Line 2 declares a procedure to call the common
bank version of CONWRD$ and clear bit 8 of the condition word. Lines 3 and 4 execute
the calls to CONWRD$ to manipulate the condition word.
7833 1733–004 7–3

CONWRD$–Condition Word Routine
7–4 7833 1733–004

Section 8
EDIT$–Fieldata Image Composition
Editing Package
EDIT$ is a unified collection of routines that may be used to compose strings of Fieldata
characters in an area that you specify. EDIT$ may produce
• Images for the printer and the punch
• Symbiont control images
• Control statements for CSF$
EDIT$ has routines for editing decimal, octal, and floating point (single and double
precision) as well as routines for copying character strings and adjusting column settings.
Routines are also available for editing the time and the date. A versatile collection of
Assembler procedures makes it easy to code for EDIT$.
EDIT$ is reentrant and uses no D-bank storage. Working storage is provided by a 6-word
packet (10 words if floating point is used) provided by the user. The format of this
packet is given in 8.1.
The EDIT$ editing package consists of four elements.
• EDIT$–general-purpose editing routines
• EDIT$T–time and date editing routines
• EDIT$F–floating-point editing routines
• EDIT$P–procedure calls for editing routines
EDIT$ does not reference the other routines. However, both EDIT$T and EDIT$F require
the services of EDIT$.
7833 1733–004 8–1

EDIT$–Fieldata Image Composition Editing Package
8.1. EDIT$–Packet Format
The EDIT$ packet format is as shown in Figure 8–1 (italicized fields are filled by the
caller).
0 ts msg il iloc
1 CIX WIX CIM WIM
2 fps fpr zero RETURN
3 RET SAVE1
4 SAVE2
5 SAVE3
6 dpc spc NDP NDF SIGN ZERO
7 FCOL SCALE
8 VALUE
9
Fields Set by the Caller
ts
msg
il
iloc
fps
fpr
Figure 8–1. EDIT$: Packet Format
This area may be used as a test-and-set flag by the user.
Signal character for EMSG$ and EMSGR$.
Image length in words.
Image location (18-bit address).
Number of digits to be placed to the left of the decimal point for scientific-format,
floating-point editing.
If nonzero, the floating-point rounding option is on; five is added to the first
significant digit after the last significant digit to be printed.
For example, if the input is 1.4356 and 3 digits are to be printed, the result is 1.44.
8–2 7833 1733–004

zero
dpc
spc
Must be zero.
EDIT$–Fieldata Image Composition Editing Package
If nonzero, specifies the character that will separate the mantissa and the exponent
for scientific-format, double-precision, floating-point editing. Normally D if nonzero.
If nonzero, specifies the character that will separate the mantissa and the exponent
for scientific format, single-precision, floating-point editing. Normally E if nonzero.
Fields Maintained by EDIT$
These fields are used only for debugging.
CIX
WIX
CIM
WIM
Used by EDITX$ to save the character index for EDITR$.
Used by EDITX$ to save the relative word index for EDITR$.
Used by EMSG$ and EMSGR$ to save the character index to the input message.
Used by EMSG$ and EMSGR$ to save the word index to the input message.
RETURN
RET
SAVE1
SAVE2
Used as the return point for the character store vector.
Used to save the return point to the user during calls to other EDIT$ functions.
Used to save the modifier portion of X1 during edit mode.
Used to save X2 during edit mode.
7833 1733–004 8–3

EDIT$–Fieldata Image Composition Editing Package
SAVE3
NDP
NDF
SIGN
ZERO
FCOL
SCALE
VALUE
Used to save X3 during edit mode.
Number of digits to be edited before the decimal point.
Number of digits to be edited following the decimal point.
Nonzero if the floating-point number being edited is negative.
Nonzero if the floating-point number being edited was not normalized.
Contains information to facilitate proper positioning of the edited result.
Used to build the exponent.
Used to save intermediate results (two words). (Used only by floating point.)
Packet Generation
Two procedures are available to generate a packet for EDIT$. The E$PKT procedure
generates a 6-word packet, and the E$PKTF procedure generates a 10-word packet
suitable for floating-point editing. The format of the procedure calls is
E$PKT il,iloc [‘MSG’,EMSG$-stop]
E$PKTF il,iloc [‘MSG’,EMSG$-stop]
[‘FPS’,fps-number] [‘FPR’,fpr-number]
[‘DPC’,dpc-char] [‘SPC’,spc-char]
The optional lists override the assumed values to be placed in the fields msg, fps, fpr,
dpc, spc. The assumed values are msg = '&', fps = 1, fpr = 1, dpc = 0, and spc = 0.
The format of an override list consists of the name of the field enclosed in quotes, a
comma, and the value to be used. For example, the following PROC reference
generates a packet that edits floating-point numbers in a format similar to that used by
FORTRAN:
PKT E$PKTF 22,LINE ‘FPS’,0 ‘FPR’,0 ‘SPC’,’E’ ‘DPC’,‘D’
8–4 7833 1733–004

EDIT$–Fieldata Image Composition Editing Package
8.2. EDIT$–General-Purpose Editing Routines
PROC Call
Before using the EDIT$ package, the caller must first establish edit mode by calling the
EDIT$ routine. When edit mode is on, the index registers X1, X2, and X3 are used as
pointers by EDIT$; do not disturb them. The original values of these registers are
restored when edit mode is turned off. The only other registers used by EDIT$ are X11,
A0, A1, A2, A3, and R1. These registers are not saved or restored. Table 8–1 describes
the routines used to initialize and terminate EDIT$.
All EDIT$ routines are called with an LMJ on X11 and expect the parameters in A0, A1,
and A2. A column pointer is maintained by EDIT$; the pointer is advanced by the
number of characters inserted whenever an editing function is performed. The first
column is zero.
Table 8–2 describes the EDIT$ routines.
Each routine in the EDIT$ editing package has a corresponding procedure call. If there
are no parameters, then load instructions are not generated and the input data is
assumed to be in the designated registers. The parameters may be in the format
"*u,*x,j".
When two parameters are required (p1, p2), the first instruction is not generated if p2 is
missing. If both p1 and p2 are missing, neither load instruction is generated. Some of
the procedures do not require any parameters.
Table 8–1. Initialization and Termination
Generated
Instructions
E$DIT p1 LA,U A0,p1
LMJ X11,EDIT$
E$DITR p1 LA,U A0,p1
LMJ X11,EDITR$
Description
Initializes and establishes edit mode.
If p1 is not specified, the address of the packet must be in A0. S3
of the first word of the packet is expected to contain the number
of words in the image area, and H2 of the first word of the packet
is expected to contain the location of the image area. The image is
set to blanks and edit mode is established. The column pointer is
set to the start of the image.
Reenters edit mode.
E$DITX LMJ X11,EDITX$ Terminates edit mode.
E$PRINT p1 LA,U A0,p1
LMJ X11,EPRINT$
If p1 is not specified, the address packet must be in A0. Edit
mode is reestablished and the column pointer (saved by EDITX$) is
restored.
The column pointer is saved in the packet. EDITX$ returns with
the packet address in A0 and the number of words in the image in
A1.
Prints image line and EDITX$.
See EPRINT$ description in Table 8–2.
7833 1733–004 8–5

EDIT$–Fieldata Image Composition Editing Package
PROC Call Generated
Instructions
E$CHAR p1 LA,U A0,p1
Table 8–2. General-Purpose Editing Routines
LMJ X11,ECHAR$
Inserts a character.
E$CLEAR LMJ X11,ECLEAR$ Clears image.
Description
The character contained in S6 of A0 is inserted into the image.
The image is set to blanks and the column pointer is set to the
start of the image (column zero).
E$COLN LMJ X11,ECOLN$ Computes the column number.
E$COL p1 LA,U A0,p1
LMJ X11,ECOL$
E$COPY p1, p2 LA,U A0,p2
LA,U A1,p1
LMJ X11,ECOPY$
E$DCFZ p1, p2 LA A0,p2
LA,U A1,p1
LMJ X11,EDCFZ$
E$DECF p1, p2 LA A0,p2
LA,U A1,p1
LMJ X11,EDECF$
E$DECV p1 LA A0,p1
LMJ X11,EDECV$
E$FD1 p1 LA A0,p1
LMJ X11,EFD1$
E$FD2 p1 DL A0,p1
LMJ X11,EFD2$
Returns with the column number in A0.
Positions to a fixed column.
The column pointer is changed to the number specified in A0.
The first character position of the image is column 0.
Copies a string.
A0 is expected to contain the address of a string of characters.
A0 increment may contain a character offset for the first word
in the range 0–5. Number of characters in A1 is copied from
this area into the image.
Edits decimal (fixed length with leading zero).
Edits A0 to a decimal number right-justified in a field of A1
characters. A leading "-" is added if A0 is negative. The result
overflows the field to the right if it does not fit into the specified
field size. Leading zeros are produced where EDECF$ would
produce leading spaces. This routine is convenient for editing
decimal fractions.
Edits decimal (fixed length).
Edits A0 to a decimal number right-justified in a field of A1
characters. A leading "-" is added if A0 is negative. The result
overflows the field to the right if it does not fit into the specified
field size.
Edits decimal (variable length).
Edits A0 to a decimal number. A leading "-" is added if A0 is
negative. The number of characters generated is a function of
the sign and magnitude of A0.
Inserts Fieldata (one word).
The six characters in A0 are inserted into the image. Blanks and
master spaces are ignored.
Inserts Fieldata (two words).
The 12 characters in A0 and A1 are inserted into the image.
Blanks and master spaces are ignored.
8–6 7833 1733–004

PROC Call Generated
Instructions
EDIT$–Fieldata Image Composition Editing Package
Table 8–2. General-Purpose Editing Routines
E$MSGR LMJ X11,EMSGR$ Message editor reentry.
E$MSG p1 LA,U A0,p1
LMJ X11,EMSG$
E$OCTF p1, p2 LA A0,p2
LA,U A1,p1
LMJ X11,EOCTF$
E$OCTV p1 LA A0,p1
LMJ X11,EOCTV$
E$PACK p1, p2 LA,U A0,p2
LA,U A1,p1
LMJ X11,EPACK$
E$PRINT p1 LA,U A0,p1
LMJ X11,EPRINT$
E$SKIP p1 LA,U A0,p1
LMJ X11,ESKIP$
Description
This routine performs the same operation as EMSG$ except
that the pointer to the input string is taken from the packet.
With these two routines, it is possible to copy a string into the
image, occasionally interrupting this process to perform other
editing functions at certain selected points in the string.
Message editor initial entry.
Copies the characters starting at the address given in A0 into
the image. This process stops when the character in S2 of the
first word of the packet is found. The pointer to this string is
saved in the packet and return is made to the user.
Edit octal (fixed length).
Edits A0 to A1 octal digits. Leading zeros are not suppressed.
A1 must not exceed 12.
Edit octal (variable length).
Edits contents of A0 to octal. The number of digits edited
depends on the size of the number. If the number is greater
than seven, a leading zero is added.
Copies and packs a string.
Same as ECOPY$ except that master spaces are ignored.
Prints image line and EDITX$.
The image pointed to by the image location in the packet is
printed and EDITX$ performed. The line spacing is given in A0.
If the parameter is omitted, a value of one is used.
Advances the column pointer.
The number given in A0 is added to the column pointer. A0
may be negative.
7833 1733–004 8–7

EDIT$–Fieldata Image Composition Editing Package
8.3. EDIT$T–Time and Date Editing Routines
Table 8–3 describes the time and date editing routines.
Each of these routines accepts input in ER TDATE$ format (see the Exec ER
Programming Reference Manual).
Month day year (relative to
1964)
Table 8–3. Time and Date Editing Routines
PROC Call Generated Instructions Description
E$DAY1 p1 LA A0,p1
LMJ X11,EDAY1$
E$DAT1 ER TDATE$
LMJ X11,EDAY1$
E$DAY2 p1 LA A0,p1
LMJ X11,EDAY2$
E$DAT2 ER TDATE$
LMJ X11,EDAY2$
E$DAY3 p1 LA A0,p1
LMJ X11,EDAY3$
E$DAT3 ER TDATE$
LMJ X11,EDAY3$
E$DAY4 p1 LA A0,p1
LMJ X11,EDAY4$
E$DAT4 ER TDATE$
LMJ X11,EDAY4$
E$DAY5 p1 LA A0,p1
LMJ X11,EDAY5$
Edits a date (mm/dd/yy).
number of seconds since midnight
Edits the date portion of A0 into the format
mm/dd/yy
where mm, dd, yy are the 2 digits of the month, day, and year,
respectively.
Edits a date (dd mmm yy).
Edits the date portion of A0 into the format
dd mmm yy
where dd and yy are the 2 digits of the day and year,
respectively, and mmm is a 3-character abbreviation for the
month.
Edits a date (month dd, year).
Edits the date portion of A0 into the format
month dd, year
where month is the name of the month (up to 9 characters),
dd is the day (one or two characters), and year is the 4-digit
year.
Edits a date (yearmmdd).
Edits the date portion of A0 into the format
yearmmdd
where year is the 4-digit year, and mm and dd are the 2 digits
of the month and day, respectively.
Edits a date (yymmdd).
8–8 7833 1733–004

EDIT$–Fieldata Image Composition Editing Package
Table 8–3. Time and Date Editing Routines
PROC Call Generated Instructions Description
E$DAT5 ER TDATE$
LMJ X11,EDAY5$
E$TIME p1 LA A0,p1
LMJ X11,ETIME$
E$TD ER TDATE$
LMJ X11,ETIME$
Edits the date portion of A0 into the format
yymmdd
where yy, mm, and dd are the 2 digits of the year, month, and
day, respectively.
Edits a time.
Edits the time portion of A0 into the format
hh:mm:ss
where hh, mm, and ss are the 2 digits of the hours, minutes,
and seconds of the time, respectively.
8.4. EDIT$F–Floating-Point Editing Routines
The floating-point editing routines require three parameters in addition to the address of
the floating-point packet. The first two are called x and y and are supplied in S5 and S6
of A0. These parameters specify the format of the edited number as described below.
The third parameter is the single- or double-precision number to be edited. If singleprecision,
the number is specified in A1; if double-precision, the number is specified in
A1 and A2.
Edited numbers may appear in one of the two general formats: fixed-decimal format
(no exponent) and scientific format. A number edited in fixed-decimal format consists of
a sign (if negative) followed by the digits of the number and an embedded decimal point.
The sign is present only if the number is negative; a positive number has no sign
character.
The parameter x specifies the width of the edited field, or the number of character
positions the edited number will occupy, including sign and decimal point. If the value of
x is too small to represent the value being edited, it is ignored, and as many character
positions as necessary are used to correctly represent the number.
The parameter y specifies how many fractional digits will be edited. This is the number
of digits appearing to the right of the decimal point. The value of y may be any value
greater than or equal to zero, but should always be less than the value of x to allow for
the sign and decimal point characters.
The scientific format is similar to the fixed-decimal format but has an exponent at the
right. The exponent consists of an optional exponent character (usually 'E' for
single-precision and 'D' for double-precision numbers) followed by the exponent's sign
(either "+" or "-") and digits. Exponents of single-precision numbers are always edited as
a 2-digit value, and those of double-precision numbers are always edited as a 3-digit
value.
7833 1733–004 8–9

EDIT$–Fieldata Image Composition Editing Package
PROC Call
The parameter x specifies the total number of character positions to be occupied by the
edited number, including signs, digits, decimal point, and exponent character. If the
edited numbers require more character positions than specified by the value of x, the
parameter x is ignored, and the required character positions are used.
The parameter y specifies the total number of mantissa digits to appear in the edited
number. It includes the digits on both sides of the decimal point but not the decimal
point itself. The placement of the decimal point within the y digits of the mantissa is
determined by the value in the packet cell FPS. This is the number of digits to appear to
the left of the decimal point. It is normally set to one.
Table 8–4 describes the floating-point editing routines.
Table 8–4. EDIT$F–Floating-Point Editing Routines
Generated
Instructions
E$FLF1 x*/6+y,p LA A1,p
LA,U A0,x*/6+y
LMJ X11,EFLF1$
E$FLF2 x*/6+y,p DL A1,p
LA,U A0,x*/6+y
LMJ X11,EFLF2$
E$FLG1 x*/6+y,p LA A1,p
LA,U A0,x*/6+y
LMJ X11,EFLG1$
E$FLG2 x*/6+y,p DL A1,p
LA,U A0,x*/6+y
LMJ X11,EFLG2$
E$FLS1 x*/6+y,p LA A1,p
LA,U A0,x*/6+y
LMJ X11,EFLS1$
E$FLS2 x*/6+y,p DL A1,p
LA,U A0,x*/6+y
LMJ X11,EFLS2$
Description
Single-precision fixed decimal format.
A1 is edited to fixed decimal format with y digits following the
decimal point, right-justified, in a field of size x.
Double-precision fixed decimal format.
A1, A2 is edited to fixed decimal format with y digits following
the decimal point, right-justified, in a field of size x.
Single-precision generalized format.
Same as scientific format except that an attempt is made to
move the decimal point in such a way as to reduce the
exponent to zero. If this can be done, the exponent is set to
blanks. Otherwise scientific format is used.
Double-precision generalized format.
See EFLG1$ and EFLS2$.
Single-precision, scientific format.
A1 is edited to scientific format with y significant digits in a
field size of x. The exponent is 2 digits long.
Double-precision, scientific format.
A1, A2 is edited to scientific format with y significant digits in
a field size of x. The exponent is 3 digits long.
8–10 7833 1733–004

Section 9
FDASC$–Fieldata/ASCII Data
Conversion
The Fieldata/ASCII conversion routine performs the following character string
conversions:
• Converts Fieldata strings to ASCII (see 9.1.1).
• Converts ASCII strings to Fieldata (see 9.1.2).
The Fieldata/ASCII conversion routine consists of the following two elements:
• FDASC$
− Converts the characters from the input string one word at a time and places
them into the output string.
− Space-fills the last word converted out to a word boundary. If the last word is all
spaces after the space filling, then the length of the output string is decreased
by one word.
− Is reentrant and does not assume quarter/third-word mode.
− Is a relocatable element in the file SYS$LIB$*SYSLIB and also collected in the
SYSLIB common bank SYSLIB$3. The relocatable and common bank entry
points for FDASC$ are listed in Appendix E.
− May be called from MASM programs.
• TABLE$
Contains the conversion codes for Fieldata and ASCII characters.
9.1. MASM Interface
The calling program may call FDASC$ as a relocatable element, a common bank
element, or a common bank element with the Auto Switch method.
9.1.1. Fieldata to ASCII Conversion
FDASC$ converts Fieldata character strings to ASCII when the FDASC$ entry point is
called. The following table lists the calling sequences.
7833 1733–004 9–1

FDASC$–Fieldata/ASCII Data Conversion
Auto Switch Common Bank or Relocatable Relocatable
L,U A0,input-buffer-word- count
L,U A1,input-buffer-address
L,U A2,output-buffer-address
LMJ X11,CBFDASC$-1
normal return
L,U A0,input-buffer-word- count
L,U A1,input-buffer-address
L,U A2,output-buffer-address
I$BJ X11,CBFDASC$
normal return
L,U A0,input-buffer-word- count
L,U A1,input-buffer-address
L,U A2,output-buffer-address
LMJ X11,FDASC$
normal return
FDASC$ converts the Fieldata characters in the input buffer (six characters per word) to
ASCII and places them into the output buffer (four characters per word, with trailing
space-fill if necessary). The length of the output buffer in words must be at least 1-1/2
times the length of the input buffer. The input buffer and the output buffer may specify
the same buffer, since the string is converted tail-to-head to prevent overwriting.
FDASC$ returns the word length of the converted ASCII image in register A0.
Example
The following example demonstrates a call to the relocatable version of FDASC$ to
convert a Fieldata character string to ASCII:
$FDATA
$INCLUDE ‘MAXR$’
$(2)
INBUF ‘SOME FIELDATA CHARACTERS.’ . Fieldata character string
INLEN $EQU $-INBUF . Word length
OUTBUF $RES INLEN*3//2 . Output buffer
PCW $GFORM 12,1, 6,0, 18,OUTBUF . Print Control Word
$(1)
START
L,U A0,INLEN . Input string word length
L,U A1,INBUF . Input string address
L,U A2,OUTBUF . Output buffer address
LMJ X11,FDASC$ . Convert FD to ASCII
.
S,S3 A0,PCW . Put word length of
L A0,PCW . converted image in PCW
ER APRINT$ . Print ASCII image
.
ER EXIT$ .
$END START .
This MASM routine calls the relocatable version of FDASC$ to convert the Fieldata string
at INBUF to ASCII. The word length of the converted image is returned from FDASC$ in
A0. An ER APRINT$ prints the converted image.
9–2 7833 1733–004

9.1.2. ASCII to Fieldata Conversion
FDASC$–Fieldata/ASCII Data Conversion
FDASC$ converts ASCII character strings to Fieldata when the ASCFD$ entry point is
called.
The following table lists the calling sequences.
Auto Switch Common Bank or Relocatable Relocatable
L,U A0,input-buffer-word- count
L,U A1,input-buffer-address
L,U A2,output-buffer-address
LMJ X11,CBASCFD$-1
normal return
L,U A0,input-buffer-word- count
L,U A1,input-buffer-address
L,U A2,output-buffer-address
I$BJ X11,CBASCFD$
normal return
L,U A0,input-buffer-word- count
L,U A1,input-buffer-address
L,U A2,output-buffer-address
LMJ X11,ASCFD$
normal return
ASCFD$ converts the ASCII characters in the input buffer (four characters per word) to
Fieldata and places them in the output buffer (six characters per word, with trailing
space-fill if necessary). The length of the output buffer in words must be at least twothirds
the length of the input buffer. The input buffer and the output buffer may specify
the same buffer, since the string is converted head to tail to prevent overwriting.
ASCFD$ returns the word length of the converted Fieldata image in register A0.
9.2. TABLE$–Fieldata/ASCII Conversion Table
TABLE$ contains the conversion codes for each ASCII and Fieldata character. Each
word of TABLE$ has the ASCII to Fieldata code in H1 and the Fieldata to ASCII code in
H2. The H2 portion of TABLE$ is used when the FDASC$ entry point is called; the H1
portion is used when the ASCFD$ entry point is called.
TABLE$ is 256 words long and has an entry point of ASCFDASC$. The H2 portion of the
last 192 words (Fieldata to ASCII codes) is unused.
TABLE$ is a relocatable element in the file SYS$LIB$*SYSLIB and is also collected in the
SYSLIB common bank SYSLIB$3.
7833 1733–004 9–3

FDASC$–Fieldata/ASCII Data Conversion
9–4 7833 1733–004

Section 10
GETPSF$–Get a Scratch File Routine
The GETPSF$ routine assigns program scratch files.
10.1. File Assignment
For greater efficiency, a common set of file names has been defined for use by system
processors, language processors, and programs that require one or more scratch files.
Based on the abbreviation PSF (program scratch file), these file names are PSF$, PSF1$,
PSF2$...PSF9$.
These files are generally assigned only once per run. The first program that requires a
file calls GETPSF$ to perform the assignment and then leaves it assigned for subsequent
use by other programs in the run. Since GETPSF$ does not initialize or clear the scratch
files, programs must assume that there may be data in the scratch file left over from its
previous use.
Programs may call GETPSF$ to assign up to 10 PSF files. To avoid the extra expense of
assigning scratch files to a run, request file PSF$ if only one file is needed. If two files
are needed, request PSF$ and PSF1$. If this convention is followed, chances are greater
that the file requested has already been assigned to the run. When a call to GETPSF$
requests the assignment of a file that is already assigned to the run, the cost to the
calling program is considerably less than if GETPSF$ actually has to assign a file.
7833 1733–004 10–1

GETPSF$–Get a Scratch File Routine
10.2. MASM Interface
The next two subsections describe the packet and the calling sequence.
10.2.1. Packet
On a call to the relocatable version of the GETPSF$ routine, the calling program passes
the number of files or the specific PSF file number to be assigned to the run.
For a call to the common bank version of the routine, the calling program must also
provide the address of a 13-word data area that is used by the GETPSF$ routine. This is
a scratch data area that does not have to be initialized by the caller and can be reused by
the calling program when control returns from GETPSF$. The packet must be in a writeenabled
bank of the calling program. The bank must also be based when the call to the
GETPSF$ routine is made.
For more information on the different methods of calling the SYSLIB routines, see
Section 3.
10.2.2. Calling Sequence
The GETPSF$ routine is called by the MASM procedure G$ETPSF. This procedure can
be used to generate the calling sequence for the relocatable version, the common bank
version, or the common bank version using the Auto Switch calling sequence.
Calling Format
G$ETPSF[,t] func-code [,n] [pkt-addr]
error return
normal return
Parameters
t
Call the relocatable version. This parameter is optional and may be omitted. CB or
A, if specified, must be enclosed by apostrophes.
blank Call the relocatable version. This is the default if t is omitted.
'CB' Call the common bank version.
'A' Call the common bank version using the Auto Switch method.
10–2 7833 1733–004

func-code
GETPSF$–Get a Scratch File Routine
The function code tells GETPSF$ how to treat the parameter n. If the function code
is set to GETPSF$, then the routine assigns scratch files in sequence beginning with
file PSF$ and continuing to file PSFn$, where n is the number given as the second
parameter.
If the function code is set to GETPSFN$, then only one file is assigned by GETPSF$.
That file is PSF$ if n is omitted or set to 0. If n is set to a value of 1 to 9, then the file
PSFn$ is assigned. The function code must be enclosed by apostrophes. The only
allowable function codes for GETPSF$ are
GETPSF$
Assign files PSF$ to PSFn$. If n is zero or is omitted, only file PSF$ is assigned.
GETPSFN$
Assign only file PSFn$. If n is zero or is omitted then file PSF$ is assigned.
Note: Any other value entered for the function code parameter on the G$ETPSF
procedure call causes MASM to generate an E flag on that line and print the error
message.
n
ILLEGAL G$ETPSF FUNCTION
The parameter n can be set to an integer value of 0 through 9. It may be given as an
actual number, a tag that has been equated to a number or the address of a word
that contains the number. The parameter n defines the highest numbered PSF file
to be assigned if a group of files is requested (that is, if the function code is set to
GETPSF$). Otherwise, n defines the particular PSF file to be assigned when the
function code is set to GETPSFN$.
If n is set to 2 and the function code is GETPSF$, then files PSF$, PSF1$, and PSF2$
are assigned. If n is set to 2 and the function code is GETPSFN$, then only one file,
PSF2$, is assigned.
pkt-addr
Address of the packet provided by the calling program to the GETPSF$ routine. This
parameter is needed only if the parameter t has been set to 'A' or 'CB'. If t is set to
'A' or 'CB', then this parameter must be included or the address of the packet must
already be in register A1. If the parameter t is blank, that is, if the call is to the
relocatable version of the GETPSF$ routine, then this parameter may be omitted.
However, including it on the call does not cause any problems.
If only the function code is given on the GETPSF$ procedure call, GETPSF uses the value
in register A0 for n. If the parameter t has been set to A or CB, then the value in register
A1 is used as the address of the packet required by the common bank routine.
7833 1733–004 10–3

GETPSF$–Get a Scratch File Routine
Normal Return
If the normal return is taken, the requested files are assigned to the run as track granular,
sector-addressable mass storage files with a maximum size of 3,000 granules. The
GETPSF$ routines do not reassign PSF files. If a PSF file is already assigned and
GETPSF$ is called to assign it again, the normal return is taken and the file remains
exactly as it was before the call to GETPSF$.
The first three characters of all files assigned by the GETPSF$ routines are always PSF.
The last three characters vary, depending on how the GETPSF$ routine was called.
These three characters are returned to the calling program in H1 of register A1 on a
normal return.
On a normal return from GETPSF$ when func-code=GETPSF$, H1 of register A1
contains "$∆∆" if only the file PSF$ was requested or "n$∆", where "n" is the highest
numbered PSF$ file requested. The symbol "∆" represents a blank.
On a normal return from GETPSF$ when func-code=GETPSFN$, H1 of register A1
contains "n$∆", where "n" is the number of the file requested or "$∆∆" if file PSF$ is
requested.
After a normal return, the calling program can store the content of register A1 into a
Fieldata string that can be submitted by ER CSF$ to attach an internal file name to the
PSF file using the @USE command. See the example.
Error Return
When the error return is taken, register A0 contains an error code with auxiliary
information in other registers. The error codes are as follows:
A0 = 0
A0 = 1
A0 = 2
The input value n is negative or exceeds 9. Register A1 contains the value.
A file is assigned to the run that is not in sector-addressable format. Register A1
points to the FACIL$ packet.
A CSF$ request was rejected. Register A1 points to the FACIL$ packet. Register A2
contains the status bits returned by CSF$.
10–4 7833 1733–004

Example
$INCLUDE ‘MAXR$/’
$(2)
PSFNUM $EQU 3
FUNCT $EQU ‘GETPSF$’
VALUE + 3
BUFFER $RES 13
BUFFLN $EQU $-BUFFER
CSFIMG ‘@USE SF,PSF ‘
$(1)
START .
G$ETPSF,‘CB’ FUNCT,3 BUFFER
J PSFERR
LXI,U X11,0
G$ETPSF ‘GETPSFN$’,PSFNUM BUFFER
J PSFERR
S A1, CSFIMG + 2
L A0, (3, CSFIMG)
ER CSF$
JN A0, PSFERR
LA,U A1,BUFFER
G$ETPSF,‘CB’ ‘GETPSF$’,VALUE
J PSFERR
J DONE
PSFERR .
L$SNAP ‘PSFERR’,2,0,0
DONE .
ER EXIT$
$END START
GETPSF$–Get a Scratch File Routine
The preceding examples all call the GETPSF$ routine to assign four temporary files to
the run (files PSF$, PSF1$, PSF2$, and PSF3$). The last call does not include BUFFER
as a parameter. Prior to making the call, the address of BUFFER must have been loaded
into register A1. The internal filename "SF" is attached to filename "PSF3$."
7833 1733–004 10–5

GETPSF$–Get a Scratch File Routine
10–6 7833 1733–004

Section 11
ID$–Identification Line Routine
ID$ provides the calling program with an identification line or lines for any processor or
program. ID$ identifies the processor called and the time it was called. The information
in the identification line consists of a processor/program description, an optional date of
creation and time for the processor/program, and the current (execution) date and time.
The System Standard Format Date and Time (SFDT$) routine formats the dates and
times. All output is in ASCII.
ID$ can be called from both MASM and PLUS programs. ID$ is available as a relocatable
element in the SYSLIB file SYS$LIB$*SYSLIB and also in the SYSLIB common bank
SYSLIB$1. The relocatable and common bank entry points for ID$ are listed in
Appendix E.
ID$ Output
The format of the identification line is
Processor/program description (creation date and time) execution date and
time
where:
Processor/program description
The calling program provides this field; it can contain any number of ASCII
characters. There are two methods to specify the description.
• A separate buffer may contain the description; the address and length in
characters are passed to ID$.
• The description can be specified as a string on the I$DPKT procedure call that
sets up the ID$ packet.
Creation date and time
ID$ obtains the date and time that the calling program was created from the
Collector-supplied values for D$ATE and T$IME. ID$ places the date and time in
parentheses using the following format: (YYMMDD HHMM:SS). Date and time are
separated from the last character of the description by one space. This field can be
excluded from the ID$ output.
7833 1733–004 11–1

ID$–Identification Line Routine
Execution date and time
ID$ uses the current date and time unless a date and time are in the ID$ packet.
(This should be the contents of R2 at load time.) Two formats are available: default is
"CCYY mmm DD ddd HHMM:SS", or optionally "YYMMDD HHMM:SS". The date
and time are separated from the last character of the creation date/time (or
description if creation date/time is excluded) by one space.
See SFDT$ routine comments for further details on the date/time formats.
The calling program can format ID$ output for 80 characters per line (demand) or 132
characters per line (batch or breakpointed-demand). If the length of the output exceeds
the maximum character length of a line, the remainder is continued on the following line.
If the creation date/time or execution date/time does not fit on one line, they are placed
entirely on the next line (there is no wraparound for date/time).
Sample displays of an ASCII string generated by ID$.
1. MASM 3R1T1 (800827 1448:46) 1983 Sep 10 Sat 1651:18
2. FURPUR 28R3 File Utility Routine/Program File Utility Routine
(820312 1356:02) 1984 May 11 Fri 1017:24
11.1. MASM Interface
The ID$ routine may be called directly from MASM programs. Subsection 11.3
describes the ID$ packet format and the MASM PROC I$DPKT that generates the
packet. Subsection 11.1.2 describes the calling sequence for ID$, the MASM PROC
I$D$ to call ID$, and the MASM PROC I$DPRINT to print the output.
11.1.1. Packet
The calling program must provide ID$ with an 11-word (or more) packet. The ID$ packet
format is described in 11.3, and the PROC to generate the ID$ packet is described
below.
The MASM PROC I$DPKT generates the packet for the ID$ routine.
Calling Format
label I$DPKT {idlen | idbuf | ‘bufname’} {hdrlen | hdrbuf | ‘string’} optbits
11–2 7833 1733–004

Parameters
label
A label to identify the start of the ID$ packet.
idlen,idbuf
ID$–Identification Line Routine
idlen is the length in words of the ID$ output buffer. idbuf is the address of the ID$
output buffer.
'bufname'
A label that identifies the output buffer which is generated immediately after the ID$
packet. This eliminates the need for a separately defined output buffer.
hdrlen,hdrbuf
'string'
optbits
hdrlen is the length in characters of the processor/program description. hdrbuf is the
address of the buffer containing the processor/program description.
The ASCII character string used as the processor/program description, which is
stored immediately after the ID$ packet. This eliminates the need for a separate
description buffer and length.
Octal number with the following bit significance (rightmost bit is 35):
Bit 35
Bit 34
Bit 33
Clear: maximum characters per line is 80.
Set: maximum characters per line is 132.
Clear: include the creation date and time.
Set: exclude the creation date and time.
Clear: use long execution date/time format.
Set: use short execution date/time format.
7833 1733–004 11–3

ID$–Identification Line Routine
Bit 32
Bit 31
Clear: line spacing for first PCW is 1 (next line).
Set: line spacing for first PCW is 07777 (top of page).
Clear: do not print the ID$ output.
Set: call I$DPRINT to print all ID$ output.
The following are two examples of generating the ID$ packet with I$DPKT:
Example 1
$(2)
IDPACKET I$DPKT ‘IDOUTPUT’ ‘Collector 31R1’
In example 1, the I$DPKT procedure generates an 11-word packet at location IDPACKET
under location counter 2. The I$DPKT procedure also allocates space following the ID$
packet for a buffer, which will contain the ID$ output. IDOUTPUT specifies the location
of the first word of this buffer. I$DPKT determines the length of the buffer (in this
example, 14 words).
I$DPKT also stores the ASCII string 'Collector 31R1' following the ID$ packet. The
options bits parameter is omitted. This sets all option bits to zero.
Example 2
$(4)
IDPAC I$DPKT 20,IDLINE 27,PGMIDENT 026
IDLINE $RES 20
PGMIDENT ‘Math Quiz Program (Level 8)’
In example 2, the I$DPKT procedure generates an 11-word packet at location IDPAC
under location counter 4. ID$ generates the identification line in the 20-word data area at
location IDLINE. ID$ uses the 27-character string at location PGMIDENT for the program
description part of the identification line.
The octal code 026 sets condition bits 34, 33, and 31. This directs ID$ to exclude the
creation date and time from the identification line, use the short format for execution
data and time, and print the identification line.
11–4 7833 1733–004

11.1.2. Calling Sequence
ID$–Identification Line Routine
ID$ is called with the MASM PROC I$D$. This PROC can call ID$ as a relocatable
element, a common bank element, or a common bank element using the Auto Switch
method.
Calling Format
I$D$[,t] pkt-addr date
error return
normal return
Parameters
t
The type of call to ID$. This parameter is optional and may be omitted. CB or A,
if specified, must be enclosed by apostrophes.
pktaddr
date
blank Call the relocatable version of ID$. This is the default if t is omitted.
'CB' Call the common bank version of ID$.
'A' Call the common bank version of ID$ using the Auto Switch method.
The address of the ID$ packet.
The address of a caller-specified date and time (it must be in TDATE$ format). This
parameter is optional.
The calling program can use indexing, incrementation, indirect addressing, and register
basing in specifying the addresses for pktaddr and date by using the $EQUF directive.
See $EQUF definitions in the MASM Programming Reference Manual.
If date is included on the calling statement, the TDATE$ value at that address is used for
the execution date/time. If the date is excluded, the TDATE$ value in word 8 of the ID$
packet is used. If no value is present in Word 8, in other words, if it is zero, the current
date/time is obtained from ER TDATE$.
7833 1733–004 11–5

ID$–Identification Line Routine
Error Return
If ID$ takes the error return, either A1 or A2 contains a negative error code. If the error
occurred in ID$, A1 contains the error code. If the error occurred in SFDT$, A2 contains
the error code.
• ID$ error codes (returned in A1)
-01 An outdated version of the ID$ packet is being used.
• SFDT$ error codes (returned in A2)
-01 through -05 SFDT$ routine error; see Section 22.
The error code is also stored in the packet, in ERRCODE.
ID$ Output
The output ID$ generates may be one or more lines. This depends on the length of the
processor/program description and specified options. For each line of ID$ output, a print
control word is constructed (line spacing, image length, image address) and stored
sequentially in the ID$ packet starting with word 10. The number of print control words
constructed is stored in S6 of word 0 of the ID$ packet.
The following procedure simplifies printing of the ID$ output:
I$DPRINT pktaddr
where pktaddr is the address of the ID$ packet.
This procedure performs an APRINT$ for each print control word. It may be called from
the I$D$ PROC by setting option bit 31.
All output from ID$ is directed to the current print file.
Normal Return
If the normal return occurs, the first print control word is returned in A0.
11–6 7833 1733–004

11.1.3. Examples
ID$–Identification Line Routine
The following example calls the ID$ routine to generate an ASCII identification line.
$ASCII
$INCLUDE ‘MAXR$’
$(2)
IDPAC I$DPKT ‘IDLINE’ ‘Math Quiz Program (Level 8)’ 026
$(1)
START
I$D$ IDPAC . Generate and print the ID line
J ERROR . Jump ahead if error return
.
. (Program code)
.
J DONE . Program complete
ERROR
L$SNAP ‘ID$’, 2 . Dump the A-registers
DONE
ER EXIT$
$END START
This MASM routine uses the ID$ routine to create and print the following identification
line:
Math Quiz Program (Level 8) 840425 1147:31
In this example, ID$ generates the ASCII identification line in the 11-word data area at
location IDLINE. The I$DPKT procedure generates the ID$ packet (see11.2.2 for details
on the I$DPKT packet generation PROC).
The I$D$ procedure calls the relocatable version of ID$, which generates the
identification line and prints it by executing an ER APRINT$ (because option bit 4 is set).
If ID$ takes the error return, L$SNAP prints the A-registers. Otherwise, the program
continues executing.
7833 1733–004 11–7

ID$–Identification Line Routine
11.2. PLUS Interface
ID$ can be called directly from PLUS programs. The data structure requirements for ID$
are described in 11.1.2. The calling sequence for ID$ is described in 11.2.2.
When ID$ is called from PLUS programs, the output is limited to a maximum of 10 lines
for the processor/program identification line(s).
11.2.1. Packet
PLUS programs that call ID$ do not need to supply a packet for ID$. Instead, the calling
program passes parameters to ID$, and ID$ builds the packet on the Automatic Storage
Stack (PLSSTACK).
The calling program must provide the following data entities:
• A buffer containing the ASCII processor/program description. It may be any length
up to ten times the maximum number of characters per line, minus the number of
characters needed for the date/time output fields. (Date/time fields require 41 or
fewer characters, depending on specified options.) The length of this buffer must be
passed to ID$ in character granularity.
• A buffer to contain the ASCII output from ID$. It must be long enough to contain the
entire output string (at most 41 characters longer than the description). ID$ will
space-fill this buffer to its end. The length of the buffer must be passed to ID$ in
word granularity.
• A 36-bit signed integer used to return error codes from ID$ to the calling program.
The above data entities must be declared LOCATABLE. These data entities are passed
to ID$ to create the identification line.
11.2.2. Calling Sequence
The following procedure declaration is required to call the ID$ routine. This procedure
must be declared by the calling program.
PROCEDURE ID_LINE( ID_OUTPUT_ADDRESS: 36 BIT MACHINE POINTER,
ID_OUTPUT_LENGTH: 36 BIT SIGNED INTEGER,
ID_NAME_ADDRESS: 36 BIT MACHINE POINTER,
ID_NAME_LENGTH: 36 BIT SIGNED INTEGER,
ID_DATE: 36 BIT MACHINE LOGICAL,
ID_OPTIONS: 36 BIT SIGNED INTEGER,
%ID_ERROR_CODE: 36 BIT SIGNED INTEGER)
IMPORTED (‘external-name’);
11–8 7833 1733–004

Parameters
ID_OUTPUT_ADDRESS
ID$–Identification Line Routine
The address of the buffer that will contain the ASCII output from ID$.
ID_OUTPUT_LENGTH
The length in words of the output buffer.
ID_NAME_ADDRESS
The address of the buffer containing the ASCII processor/program description.
ID_NAME_LENGTH
The length in characters of the processor/program description buffer.
ID_DATE
The execution date and time; it may be a value in TDATE$ format, or set to minus
one (-1) to use current date and time.
ID_OPTIONS
Bit 36
Bit 35
Bit 34
Bit 33
An octal number that specifies which options ID$ uses (bit 36 is the rightmost bit of
ID_OPTIONS).
Clear: maximum characters per line is 80.
Set: maximum characters per line is 132.
Clear: include the creation date and time.
Set: exclude the creation date and time.
Clear: use long execution date/time format.
Set: use short execution date/time format.
Clear: line spacing for first PCW is 1 (next line).
Set: line spacing for first PCW is 07777 (top of page).
7833 1733–004 11–9

ID$–Identification Line Routine
Bit 32
Clear: do not print the ID$ output.
Set: Print the ID$ output.
ID_ERROR_CODE
Contains the error code (if any) returned by ID$.
external-name
One of two entry points to ID$:
ID$P
ID$PG
For modules compiled without the G option. Calls the relocatable version of ID$.
For modules compiled with the G option (I$BJ procedure and function calling
sequence). Calls the common bank version of ID$.
If after calling ID_LINE, ID_ERROR_CODE is zero, then the call to ID_LINE was
successful; ID_OUTPUT_ADDRESS now contains the output string. If
ID_ERROR_CODE is negative, an error occurred (see 11.1.2).
11–10 7833 1733–004

11.2.3. Example
The following example uses ID$ in a PLUS program:
MODULE;
DECLARE ID_BUFFER: 80 ASCII CHARACTERS LOCATABLE,
DESCRIPTION: 32 ASCII CHARACTERS LOCATABLE,
ERROR: 36 BIT SIGNED INTEGER LOCATABLE;
"
PROCEDURE ID_LINE( ID_OUTPUT_ADDRESS: 36 BIT MACHINE POINTER,
ID_OUTPUT_LENGTH: 36 BIT SIGNED INTEGER,
ID_NAME_ADDRESS: 36 BIT MACHINE POINTER,
ID_NAME_LENGTH: 36 BIT SIGNED INTEGER,
ID_DATE: 36 BIT MACHINE LOGICAL,
ID_OPTIONS: 36 BIT SIGNED INTEGER,
%ID_ERROR_CODE: 36 BIT SIGNED INTEGER)
IMPORTED (‘ID$P’);
.
.
.
DESCRIPTION:= ‘Weekly Status Reports’;
ID_LINE(LOC(ID_BUFFER),20,LOC(DESCRIPTION),21,-1,0’32’,%ERROR);
.
.
ID$–Identification Line Routine
In this example, the calling program calls the relocatable version of ID$. ID$ places the
identification line into "ID_BUFFER", with no creation date and time. The ID$ routine
uses the current date and time for the creation date and time. ID$ places output at the
top of the next page and sends it immediately to the current print file.
7833 1733–004 11–11

ID$–Identification Line Routine
11.3. Packet Format
The following shows the ID$ packet format. The calling program must provide
appropriate values for the fields in italics.
0 tscell pktvers pktlen linelim qwmflg numpcw
01 optbits idlen hdrlen
02 idbuf
03 hdrbuf
04 numwrds datefmt timefmt reserved (must be zero) sfdtvers
05 offset sfdtnch sfdtlen errcode
06 sfdtbuf
07 crdate
010 exdate
011 X11save
012 pcword
012+1 pcword 1
012+n pcword n
Packet Fields
tscell
pktvers
pktlen
linelim
bufspace
Available to the calling program as a test-and-set cell (optional).
The packet version number (for code maintenance only). The current version is 1
(required).
The length in words of the ID$ packet (required). This includes the length through
the last allocated PCW.
qwmflg
The maximum length in words of the output lines (either 20 or 33 words) (required).
Quarter Word Mode flag; set to a positive value if ID$ changes to QWM; otherwise
zero.
11–12 7833 1733–004

numpcw
optbits
idlen
hdrlen
idbuf
hdrbuf
Number of Print Control Words necessary for the ID$ output.
The octal number that specifies available ID$ options (optional).
The length in words of the ID$ output buffer (required).
ID$–Identification Line Routine
The length in characters of the processor/program description (required).
The address of the ID$ output buffer (required).
The address of the buffer containing the processor/program description (required).
numwrds
datefmt
timefmt
A running total of the number of words written out to the current output line.
The date format index for SFDT$.
The time format index for SFDT$.
sfdtvers
offset
The SFDT$ packet version; see SFDT$ routine (Section 22) for the current version
(required).
sfdtnch
sfdtlen
The character offset within the first word (0 to 3) of the ID$ output (optional).
The number of characters that SFDT$ writes.
The length in words of output buffer for SFDT$.
7833 1733–004 11–13

ID$–Identification Line Routine
errcode
sfdtbuf
crdate
exdate
A negative error code returned from ID$ or SFDT$.
The address for output from SFDT$ (contained within the ID$ output buffer).
If the MASM PROC, I$DPKT, is not used to generate this packet, crdate must be
specified by the user if optbits bit 34 is clear. For example, this value can be entered
as
+ D$ATE*/18+T$IME
which will then be resolved at collection time. The value contained in this word will
be interpreted as a date and time, whether or not it was specified as such. If a value
of zero is used, the current date and time at execution will appear on the ID line in
the position of the creation date and time.
The execution date and time in TDATE$ format (optional).
X11save
pcword
Storage space for return address.
Storage space for the first ID$ output print control word (PCW).
pcword n
Storage spaces for n additional PCWs, when more than one PCW is required for the
ID$ output. If the ID image is longer than that allowed by the number of allocated
PCWs, the ID line is truncated.
bufspace
Storage space reserved for the ID$ output buffer, the processor/program description
buffer, or both. Space is reserved only if requested in packet generation (see the
I$DPKT description), and allocated immediately after the ID$ packet.
Words 4 to 8 of the ID$ packet are the packet for SFDT$ (Standard Format Date and
Time routine).
11–14 7833 1733–004

Section 12
INFOR$–Internal Format Table Interface
Routines
The INFOR interface routines read the INFOR table into memory, search through the
table for specific information, retrieve information from the INFOR table, and dynamically
assign internal use names to files.
The INFOR routines can be included in the calling program as relocatable elements or
can be referenced from one of the SYSLIB common banks by either the I$BJ or the Auto
Switch method. For a complete description of these calling methods see Section 3.
Appendix E includes a list of the SYSLIB common bank names and the routines included
in them.
Internal format (INFOR) refers to the data format used to pass information from the
processor call statement to a program when it is called as a processor instead of being
called by an @XQT command. The difference between calling a program as a processor
and calling it by an @XQT statement is how the first read instruction of the program is
executed. If the program is called by the @XQT command:
@XQT PROGRAM file.element/version
then there is nothing different about how the first read instruction is executed. It is
executed like any other read in the program. When the read instruction is encountered
the program stops and waits for data to be entered. The extra information entered on
the call line, (in this example, file.element/version,) is ignored. If the program is called as
a processor:
@PROGRAM file.element/version
then the first read receives information from the processor call statement in internal
format. More than one read command may be needed to read all the information.
When all information has been read into memory, it is refered to as the INFOR table.
A processor can accomplish this by calling the INFOR$ routine RINF$ (Read Internal
Format). Having the data from the call line placed in a table with a predefined format and
then having a common set of routines to access this table gives processors a fast and
efficient means of getting at the information they need.
7833 1733–004 12–1

INFOR$–Internal Format Table Interface Routines
12.1. Format of the Internal Format Table
See Appendix G for the structure of the INFOR table and the identifiers used to
reference the information it contains.
12.2. General Considerations for Using the INFOR
Routines
If the calling program uses the relocatable version of the INFOR$ routines, the INFOR$
routine allocates a 28-word packet under location counter 2. Normally this results in the
area being defined in the calling program data bank. The actual location of the packet
can be specified by the calling program through the use of Collector directives that
define where data items under specific location counters are to be put. The following
data area labels are externally defined by the relocatable version of the INFOR$ routines.
These labels reference data areas in the 28-word packet and, since they are externalized,
they can be used by the calling program.
INFOR$
Flag used by RINF$ to determine if the INFOR table has already been read.
INFOR$+1
FILE$
ELT$
Contents of A0 after first READ$ performed by RINF$ (status bits, CLIST$ index, and
so on).
Edited file name from DUSE$ (8 words).
Field description table from SELT$ (14 words).
If the calling program uses the common bank form of the INFOR$ routines, the calling
program must provide a 30-word packet in a write-enabled bank that is based when the
call to the INFOR$ routine is made. This packet can be generated by including a call to
the procedure I$NFORPKT in the calling program code. This procedure reserves 30
words of space and externalizes the data area tags INFOR$, FILE$, and ELT$. (See the
definitions for INFOR$, FILE$, and ELT$ listed above.)
The I$NFORPKT procedure should not be used when the relocatable version of INFOR$
is called because the procedure I$NFORPKT and the relocatable version of INFOR$
externalizes these tags.
12–2 7833 1733–004

INFOR$–Internal Format Table Interface Routines
The only values allowed for the function code on the I$NFOR procedure call are RINF$,
SINF$, SELT$, and DUSE$. Any other value entered for the function code parameter on
the I$NFOR procedure call causes MASM to generate an E flag on that line and print the
error message:
ILLEGAL I$NFOR FUNCTION
All of the code in the INFOR$ routines is I-bank reentrant. The INFOR$ code is quarterword
and third-word insensitive.
12.3. INFOR$–Routines
The INFOR$ routines are a set of routines that read and manipulate the INFOR table.
The INFOR$ routines are:
• RINF$
Read the INFOR table into memory.
• SINF$
Search the INFOR table for a specification subfield.
• SELT$
Transfer a subfield from the INFOR table to the ELT$ table.
• DUSE$
Perform a dynamic @USE to attach an internal name to a file (see ECL and FURPUR
Reference Manual.
Limitation of INFOR Routines
Because the field number (the FN subfield, see Appendix G) is limited to 6 bits, only 63
fields (octal 1 to octal 77) can be uniquely numbered in the INFOR table. If more than 63
fields are given, then the field numbers start over going from 1 to 63 again. For
example, if a processor had 68 parameters on its call line, all 68 parameters would be
included in the INFOR table. However, they would be numbered 1 to 63 and then 1 to 5.
In this case, the INFOR$ routines SINF$ and SELT$ cannot be used to access the last
five fields.
The field number given on these calls must be in the range of 1 to 63, and the
information returned would always come from one of the first 63 fields. If a programmer
wishes to allow more than 63 parameters on the call line, the RINF$ routine can be used
to create the INFOR$ table but all subsequent processing of the data would have to be
done by the processor itself.
7833 1733–004 12–3

INFOR$–Internal Format Table Interface Routines
12.3.1. RINF$–Read INFOR Table
The RINF$ routine performs a read operation to read the INFOR table and store it in an
area that the calling program supplies. The RINF$ routine must be called before the
SINF$, the SELT$, or the DUSE$ routines may be used.
INFOR$ is a word defined externally by the INFOR$ routine. If it is zero, then the RINF$
routine executes a read instruction and reads the INFOR table into the area indicated by
parameter start-addr. If INFOR$ is not zero, RINF$ assumes that the INFOR table has
already been read and immediately does a normal return to the caller. The calling
program must set INFOR$ to zero if the calling program is reusable and is making
multiple calls to the RINF$ routine.
The RINF$ routine is called by the MASM procedure I$NFOR. This procedure can be
used to generate the calling sequence for the relocatable version of the RINF$ routine,
the common bank version of the routine, or the common bank version of the routine
using the Auto Switch calling sequence. Section 3 describes the advantages and
disadvantages of using the different types of calls.
Calling Format
I$NFOR[,t] ‘RINF$’[,word-count,start-addr] [packet]
error return
normal return
Parameters
t
RINF$
Type of call to RINF$. This parameter is optional and may be omitted. CB or A, if
specified, must be enclosed by apostrophes.
blank Call the relocatable version of RINF$. This is the default if t is omitted.
'CB' Call the common bank version of RINF$.
'A' Call the common bank version of RINF$ using the Auto Switch method.
RINF$ is the function code which specifies which of the INFOR$ routines the
procedure I$NFOR should call. It must be enclosed by apostrophes.
word-count
Length in words of the memory area provided by the caller into which the RINF$
routine is to store the INFOR table. If this parameter is omitted, the RINF$ routine
uses the value in H1 of register A0 as the length.
12–4 7833 1733–004

INFOR$–Internal Format Table Interface Routines
To determine the length of the memory area needed to store the INFOR table, see the
section, "Determining the INFOR Table Size" in Appendix G. After this size value is
calculated, add 28 to it. The additional 28 words are needed because one extra word is
used for a word of zeroes that RINF$ puts after the last word of the INFOR table and 27
extra words are used as an overflow area when RINF$ reads the last block of INFOR
data.
Word-count = (size value calculated using Appendix G) + 28.
start-addr
packet
Address of the data area in which the RINF$ routine stores the INFOR table. If this
parameter is omitted, the RINF$ routine uses the value in H2 of register A0 as the
starting address of the data area.
Address of the 30-word packet required by the common bank version of INFOR$
routine. This parameter is ignored unless parameter t is set to 'A' or 'CB'. If the
common bank version of the RINF$ routine is being called and this parameter is
omitted, then the routine assumes the address has already been loaded into register
A2 by the calling program.
Returns
If the normal return is taken, the INFOR table has been read into the area specified by
parameter start-addr followed by a zero-filled word. H2 of register A1 contains the
address of this word.
If the error return is taken, register A1 contains the error code and register A0 contains
the PRINT$ control word for the error message. Table 12–1 lists the possible messages.
Table 12–1. INFOR$: RINF$ Error Messages
Error Code Error Message and Description
1 PROCESSOR CALL ERROR
Data images were returned on the first call to READ$, indicating that no INFOR
table was created for this program.
2 ABNORMAL RETURN FROM READ$
READ$ returned with an end-of-file or other status that indicates this program
has neither an INFOR table nor input data images.
3 TOO MANY SPECIFICATIONS
The buffer area is not large enough to hold the INFOR table.
7833 1733–004 12–5

INFOR$–Internal Format Table Interface Routines
12.3.2. SINF$–Search INFOR Table
SINF$ searches the INFOR table (previously read by RINF$; see 12.3.1) for a
specification subfield.
The SINF$ routine is called by the MASM procedure I$NFOR. This procedure can be
used to generate the calling sequence for the relocatable version of the routine, the
common bank version of the routine, or the common bank version of the routine using
the Auto Switch calling sequence. Section 3 describes the advantages and
disadvantages of using the different types of calls.
Calling Format
I$NFOR[,t] ‘SINF$’[,ftfnsfn] [packet]
no-find-return
find return
Parameters
t
SINF$
ftfnsfn
Type of call to SINF$. This parameter is optional and may be omitted. CB or A,
if specified, must be enclosed by apostrophes.
blank Call the relocatable version of SINF$. This is the default if t is omitted.
'CB' Call the common bank version of SINF$.
'A' Call the common bank version of SINF$ using the Auto Switch method.
SINF$ is the function code which specifies which of the INFOR$ routines the
procedure I$NFOR should call. It must be enclosed by apostrophes.
Subfield specification that the SINF$ routine is to search for.
ft Field type (see FT in Appendix G)
fn Field number (see FN in Appendix G)
sfn Subfield number (see SFN in Appendix G)
The field type value may only be 1 (specification field). If 0 is specified, SINF$ will
use a field type value of 1. The field number value may be equal to or greater than
01. The subfield number may be a number between 01 and 10 8 . For example, to
return the element name subfield of field 3, the parameter would be set to 010306.
If this parameter is omitted, the SINF$ routine assumes the calling program has
already loaded the information into H2 of register A0.
12–6 7833 1733–004

packet
INFOR$–Internal Format Table Interface Routines
Address of the 30-word packet required by the common bank version of INFOR$
routine. This parameter is ignored unless parameter t is set to 'A' or 'CB'. If the
common bank version of the SINF$ routine is being called and this parameter is
omitted, then the routine assumes the address has already been loaded into register
A2 by the calling program.
Returns
There is a special case where an element name is preceded by a period and entered
without a filename.
@processor .element
This is normally interpreted to mean that the file name for the present subfield is either
TPF$ (if it is the first subfield) or it is the same file name as in the previous subfield.
When SINF$ is used to retrieve the element name and this condition exists, SINF$
makes a normal find-return to the calling program with the element name in the register
pair A0,A1 and sets the FCI field in the subfield control word to an octal 75. (Octal 75 is
the Fieldata code for a period.) Register A2 contains the address of the subfield control
word and the following test can be used to detect this condition.
TNZ,S4 0,A2
The instruction immediately after the TNZ will be skipped if the element name was given
on the processor call line with a leading period but no file name.
Another special case is when there is no qualifier in a field but an asterisk precedes the
file name.
@processor *file.
In this case, if SINF$ is used to retrieve the qualifier, it makes a normal find-return to the
calling program with blanks in the register pair A0,A1. When the processor call line
specifies a file name with no qualifier or leading asterisk
@processor file.
SINF$ takes the no-find-return if asked to retrieve the qualifier.
When a find-return occurs, the registers contain:
A0,A1 the contents of the specified subfield in Fieldata (left-justified, space-filled).
A2 (H2) location of subfield control word (see Appendix G).
A3 number of characters.
When a no-find-return occurs, A2 points to the word that stopped the search. If this
word is zero, the end of the INFOR table has been reached.
7833 1733–004 12–7

INFOR$–Internal Format Table Interface Routines
12.3.3. SELT$–Transfer to ELT$ Table from INFOR Table
The SELT$ routine transfers a field from the INFOR table to the ELT$ table.
The SELT$ routine is called by the MASM procedure I$NFOR. This procedure can be
used to generate the calling sequence for the relocatable version of the SELT$ routine,
the common bank version of the routine, or the common bank version of the routine
using the Auto Switch calling sequence. Section 3 describes the advantages and
disadvantages of using the different types of calls.
Calling Format
I$NFOR[,t] ‘SELT$’[,ftfn] [packet]
no-find return
find-return
Parameters
t
SELT$
ftfn
Type of call to SELT$. This parameter is optional and may be omitted. If CB or A is
specified, it must be enclosed by apostrophes.
blank Call the relocatable version of SELT$. This is the default if t is omitted.
'CB' Call the common bank version of SELT$.
'A' Call the common bank version of SELT$ using the Auto Switch method.
SELT$ is the function code which specifies which of the INFOR$ routines the
procedure I$NFOR should call. It must be enclosed by apostrophes.
Field that is transferred to the ELT$ table from the INFOR table. If this parameter is
omitted, the SELT$ routine uses the value in H2 of register A0. The value in S5 of
A0 is the field type and the value in S6 of A0 is the field number of the field to be
transferred.
ft Field type (see FT in Appendix G).
fn Field number (see FN in Appendix G).
The field type value may only be 1 (specification field). If 0 is specified, SELT$ will
use a field type value of 1. The field number value may be 1 or greater.
12–8 7833 1733–004

packet
INFOR$–Internal Format Table Interface Routines
Address of the 30-word packet required by the common bank version of INFOR$
routine. This parameter is ignored unless parameter t is set to 'A' or 'CB'. If the
common bank version of the SELT$ routine is being called and this parameter is
omitted, then the routine assumes the address has already been loaded into register
A2 by the calling program.
ELT$ Table Format
Figure 12–1 displays the ELT$ table fields.
0 5 6 11 12 17 18 23 24 29 30 35
ELT$+0 FQL FNL FCL RKL WKL IQF
+1 ENL EVL ECL CFN ECC BEC
+2 FQUAL
+3 (two words)
+4 FNAME
+5 (two words)
+6 FCYC
+7 RKEY
+8 WKEY
+9 ENAME
(two words)
+11 EVER
(two words)
ELT$+13 ECYC
Figure 12–1. INFOR$: Format of the ELT$ Table
The Assembler procedure, ELT$, defines the field names in the ELT$ table (see Figure
12–1) as EQUF and EQU directives.
7833 1733–004 12–9

INFOR$–Internal Format Table Interface Routines
Field Descriptions
The fields in Figure 12–1 represent the following:
FQL Length (in characters) of file qualifier or zero
FNL Length (in characters) of file name or zero
FCL Length (in characters) of F-cycle or zero
RKL Length (in characters) of read key or zero
WKL Length (in characters) of write key or zero
IQF Implied qualifier flag
ENL Length (in characters) of element name or zero
EVL Length (in characters) of element version or zero
ECL Length (in characters) of element cycle or zero
CFN File continuation field number or zero
ECC Element cycle signal character
BEC Binary element cycle
FQUAL Fieldata file qualifier
FNAME Fieldata file name
FCYC Fieldata F-cycle
RKEY Fieldata read key
WKEY Fieldata write key
ENAME Fieldata element name
EVER Fieldata element version
ECYC Fieldata element cycle
SELT does not clear ELT$. The calling program should test which field lengths of the
first two words are nonzero. This determines which Fieldata fields contain meaningful
information. If a Fieldata field is defined, the information it contains is left-justified and
space-filled to one or two words.
If the field selected by SELT$ contains a leading period, then the CFN field is set.
The CFN field contains the number of the last field that did not contain a leading period.
For example
@PROCESSOR F.E1,E2,.E3
12–10 7833 1733–004

INFOR$–Internal Format Table Interface Routines
The element E3 is assumed to be in the same file as element E2. If the SELT$ routine is
called to transfer the third field into the ELT$ table, then CFN is set to 2. Because there
is no file name and no leading period in the second field, it is assumed that E2 is in file
TPF$. Since TPF$ is an assumed file and not explicitly included on the processor call
line, the field FNL is set to zero. In the following example:
@PROCESSOR F.E1,.E2,.E3
field two contains a leading period. The element E3 is still assumed to be in the same
file as E2. By the same convention, element E2 is assumed to be in the same file as
element E1. In this case, when SELT$ is called to transfer the third field of the
processor call line, CFN is set to 1, FNL is set to 1, and the field FNAME in ELT$ is set to
the Fieldata character string F.
A leading asterisk sets the implied qualifier flag (IQF) to nonzero and the file qualifier
length (FQL) to zero.
SELT$ handles element cycles from the processor call line as follows:
• If the element cycle field is not specified, the element cycle signal character (ECC)
equals a Fieldata minus sign (-), and the Binary Element Cycle (BEC) equals zero.
• When the element cycle field is specified, the numeric portion of the cycle is
converted to binary and the result is placed in BEC.
• If the cycle is neither numeric nor signed numeric or is greater than 63, the field ECC
contains the Fieldata image E, which indicates an error. Normally, ECC contains 0,
Fieldata +, or Fieldata - when the first character of the cycle is numeric, +, or -,
respectively.
No-find Return
When a no-find return occurs, register A0 contains the address of the control word in the
INFOR table that stopped the search. If this word is zero, the rest of the INFOR table is
empty.
12.3.4. DUSE$–Assign a USE Name to the File in ELT$
The DUSE$ routine dynamically attaches an internal name to the file currently in the
ELT$ table.
The DUSE$ routine is called by the MASM procedure I$NFOR. This procedure can be
used to generate the calling sequence for the relocatable version of the DUSE$ routine,
the common bank version of the routine, or the common bank version of the routine
using the Auto Switch calling sequence. Section 3 describes the advantages and
disadvantages of using the different types of calls.
Calling Format
I$NFOR[,t] ‘DUSE$’[,use-name] [packet]
return
7833 1733–004 12–11

INFOR$–Internal Format Table Interface Routines
Parameters
t
Type of call to DUSE$. This parameter is optional and may be omitted. If CB or A is
specified, it must be enclosed by apostrophes.
blank Call the relocatable version of DUSE$. This is the default if t is omitted.
'CB' Call the common bank version of DUSE$.
'A' Call the common bank version of DUSE$ using the Auto Switch
method.
DUSE$
DUSE$ is the function code which specifies which of the INFOR$ routines the
procedure I$NFOR should call. It must be enclosed by apostrophes.
use-name
packet
The use name that is to be attached to the file currently in the ELT$ table. The use
name may be from 1 to 12 characters selected from the set A through Z, 0 through
9, including the special characters - and $. If given as a string, then this parameter
must be surrounded by apostrophes on the procedure call. This parameter may also
be given as the address of a two-word area that contains the name in Fieldata
format, left-justified and space-filled. If the use-name parameter is not specified in
the DUSE$ call, the use name is assumed to be contained by registers A0 and A1.
Address of the 30-word packet required by the common bank version of INFOR$
routine. This parameter is ignored unless parameter t is set to 'A' or 'CB'. If the
common bank version of the INFOR$ routines is being called and this parameter is
omitted, then the routine assumes the address has already been loaded into register
A2 by the calling program.
Return
After the return, register A0 contains the status bits from CSF$ (see the Exec ER
Programming Reference Manual for information). The eight-word area, FILE$, contains
the edited file name, left-justified, and space-filled). If a file name is not specified (FNL =
0), TPF$ is assumed to be the default file.
12–12 7833 1733–004

Section 13
MFDSP$–Master File Directory Service
Package
MFDSP$ retrieves information about files from the master file directory (MFD). A copy
of the MFD is needed before the MFDSP$ routine can be used. The MFD copy is
produced by a call to ER MSCON$ (using the DGET$ or DGETP$ function). Once this
copy of the MFD is in a mass storage file that is assigned to the calling program, the
MFDSP$ routine can be used to retrieve the lead items, main items, and device area
descriptor (DAD) tables of all the files in the MFD. A complete description of how the
ER MSCON$ is used and what information is contained in lead items, main items, and
DAD tables can be found in the Exec Installation and Configuration Guide.
The copy of the MFD can also be obtained by initially calling MFDSP$ with function code
10. MFDSP$ then does an ER MSCON$ DGET$ function to copy the MFD to a scratch
file that MFDSP$ has assigned.
The following subsections describe the packet needed by the MFDSP$ routine, as well
as the MASM calling sequence.
13.1. Packet
The MFDSP$ routine requires that the calling program provide it with a packet. The first
two words of the MFDSP$ packet must contain (in Fieldata LJSF) the internal file name
of the file that holds the output from the ER MSCON$. This file must be assigned
before the call to MFDSP$ can be made. Failure to have the file assigned results in an
I/O error type 01, code 21, contingency 12.
The MFDSP$ routine uses the remainder of the packet as scratch space. Since the
routine does track-size double-buffered I/O, the packet must be large enough to hold two
I/O packets, two track-size buffers, and additional space required by the MFDSP$ routine
for its internal tables. In general, a packet of 4,400 words is an adequate starting size.
Once the ER MSCON$ file is successfully initialized, the exact packet size required is
returned in register A5. The packet length may have to be increased if a 02 error is
returned.
7833 1733–004 13–1

MFDSP$–Master File Directory Service Package
13.2. Calling Sequence
The MFDSP$ routine is called by the MASM procedure M$FDSP. M$FDSP is used to
generate the calling sequence for the relocatable version, the common bank version, or
the common bank version using the Auto Switch calling sequence. Section 3 describes
the advantages and disadvantages of using the different types of calls.
Calling Format
M$FDSP[,t] pkt-length,pkt-addr,func-code,device-table-size
error return
normal return
Parameters
t
Type of call to MFDSP$. This parameter is optional and may be omitted. CB or A, if
specified, must be enclosed by apostrophes.
pkt-length
blank Call the relocatable version of MFDSP$. This is the default if t is
omitted.
'CB' Call the common bank version of MFDSP$.
'A' Call the common bank version of MFDSP$ using the Auto Switch
method.
The length of the packet provided by the calling program to the MFDSP$ routine.
In general, a packet length of 4400 words is needed by MFDSP$. If this parameter
is omitted, then the routine uses the value in H1 of register A0 as the packet length.
The packet length parameter can be given as an actual number, a tag that has been
equated to a number, or the address of a word that contains the packet length
(see 13.4.).
pkt-addr
The address of the packet provided by the calling program to the MFDSP$ routine.
The first two words of the packet must contain the internal file name (12 Fieldata
characters, left-justified and space-filled format) of the file created by using the
ER MSCON$. The rest of the packet is used by the MFDSP$ routine for I/O buffers
and internal I/O packets and tables. If this parameter is omitted, then the routine
uses the value in H2 of register A0 as the address of the packet.
13–2 7833 1733–004

func-code
MFDSP$–Master File Directory Service Package
The function code may be given as an actual number, a tag that has been equated to
an actual number, or the address of a word that contains the number. The first time
the MFDSP$ routine is called, it must be called with a function code of zero or one.
If the MFD file was created using the DGET$ function on the ER MSCON$, then use
zero on the MFDSP$ call. If the MFD file was created using the DGET$P function on
the ER MSCON$, then a function code of one must be used on the MFDSP$ call.
If this parameter is omitted, the routine uses the value in H2 of register A1 as the
function code. If device-table-size is specified as the fourth parameter then this
parameter is required.
The function codes for MFDSP$ are the following:
0 Initialize for DGET$ file and return the address of the first lead item.
1 Initialize for DGETP$ file and return the address of the first main item.
2 Get next lead item (DGET$ file only).
3 Get sector 1 of lead item (DGET$ file only).
4 Get next main item.
5 Get next sector of main item.
6 Get first DAD table associated with the main item returned by function 4 or 5.
7 Get next DAD table.
8 Find item whose MFD address is in A2.
9 Convert MFD address in A2 to DGET$ file relative address in A3.
10 Get a ER MSCON$ (DGET$) copy of the MFD and initialize (function code 0)
device-table-size
If this parameter is omitted, the default maximum size of the device number table is
1,000 words. The device table is a buffer built by MFDSP$ to contain a 1-word entry
for each mass storage device configured on the system. Entries are located in the
table according to the device number or LDAT index (see the Exec System Software
Administration Reference Manual (subsection 2.2) for more information on the LDAT
index). This means that if a device is numbered 100, its entry will occupy the 101 st
word of the table (entries begin at the second word of the table). If this parameter is
included, the ‘func-code’ parameter must also be included.
The default maximum size of the device number table is 1,000 words. If your system
includes devices numbered greater than 999, you can use this parameter to increase
the table size to a maximum of 4,096 words. The requested word size of the table
should be at least the highest device number plus 1. A device-table-size value of
1000 or less will use the current table size of 1,000 words. The pkt-length
(parameter 1) should also be increased when a larger device table size is requested
by the fourth parameter. The device table size parameter is only used by functions
that initialize the device table (functions 0, 1, and 10.) The value of this parameter is
passed in H1 of register A1.
7833 1733–004 13–3

MFDSP$–Master File Directory Service Package
Returns
On all returns, registers A0 through A3 are set as follows:
A0
A1
A2
A3
A5
Unchanged.
Main storage address of requested item or zero if the requested item could not be
found.
Item type bits (rightmost bit is bit 35):
Bit 35 Lead item
Bit 34 Sector 0 or first item
Bit 33 Sector 1 or extension or continuation item
Bit 31 Main item
Bit 29 DAD table
Bits 33 and 34 may be set with any of the other bits.
For example, if A2 = 0102, then the item returned is the first DAD table.
Error code (if error return is taken). Zero if the item is not found.
MFD address of requested item or zero if the requested item could not be obtained.
Amount of D-bank required for the packet supplied to MFDSP$.
13–4 7833 1733–004

13.3. Error Conditions
MFDSP$–Master File Directory Service Package
On error return, registers A4 and A5 sometimes contain additional information. MFDSP$
error codes (returned in register A2) are as follows:
01
02
03
04
05
06
Function out of range.
Buffer too small.
A4 = one of the following values, indicating the type of buffer size error:
1
2
3
Buffer smaller than minimum scratch space required to do any function.
This code is only returned if the buffer is smaller than 200 words.
Buffer is too small to complete initialization of the DGET$ or DGETP$ file.
Buffer is large enough to complete initialization of the file but is not large
enough to do double-buffered I/O on the file.
A5 = Amount of buffer space required.
In all cases, the calling program may obtain the required amount of buffer space and
reinitialize the package.
Illogical function sequence; for example, a request was made to obtain a main item
extension sector when the preceding request was not for a main item.
Bad link to lead item sector 1; A3 = MFD address in error.
Bad link from lead item to main item; A3 = MFD address in error.
Main item does not have MBIT set.
7833 1733–004 13–5

MFDSP$–Master File Directory Service Package
07
010
011
012
013
014
015
016
017
020
021
Main item does not link back to lead item.
Name in main item not same as name in lead item.
Calculated F-cycle does not match F-cycle in main item.
Bad link to main item extension; A3 = MFD address in error.
Main extension does not link back to main item.
Name in main item extension not same as name in lead item.
Main extension has bad sentinel.
Bad link to first DAD; A3 = MFD address in error.
Bad link from DAD to DAD; A3 = MFD address in error.
Undefined MFD address passed by caller.
MFD address conversion error. A DAS was found with a track address in word zero
that was invalid.
A3
MFD address in error.
13–6 7833 1733–004

022
023
024
025
026
027
A5
041 LDAT index in range but not defined.
042 LDAT index too large.
043 Track offset into unit too large.
044 Track not allocated.
MFDSP$–Master File Directory Service Package
This is a fatal error. Reinitialization of the package is not possible.
I/O error reading sector zero of DGET$ file.
A4 Address of I/O packet.
A5 I/O status code.
I/O error reading first directory track.
A4 Address of I/O packet.
A5 I/O status code.
More than one unit with same LDAT. This is a fatal error in the structure of the
MFD. Reinitialization of the package is not possible.
DAS in unallocated track. This is a fatal error in the structure of the MFD.
Reinitialization of the package is not possible.
Bad I/O status reading DAS.
A4 Address of I/O packet.
A5 I/O status code.
Garbage lead item. A lead item was found that contained invalid links to all main
items.
7833 1733–004 13–7

MFDSP$–Master File Directory Service Package
030
031
032
033
034
035
070
071
077
Error in structure of MFD. This is a fatal error in the structure of the MFD.
Reinitialization of the package is not possible.
Too many units configured. Either there is an error in the MFD or the number of
different units configured is greater than the parameter MAXUNT. MAXUNT is set
to 1,000 in the released version.
Bad main item in DGETP$ file. A main item from a DGETP$ file was found to have
an invalid link to the first DAD table or the first DAD table did not link back to the
main item.
Error return from ER MSCON$ (status word in register A4). See the Exec
Administration Reference Manual.
Error return from GETPSF$ (status in register A4).
A device table size of more than 4,096 words was requested by the fourth call
parameter “device-table-size.”
Function undefined.
Internal error.
I/O error.
A4 Address of I/O packet.
A5 I/O status code.
13–8 7833 1733–004

13.4. Examples
MFDSP$–Master File Directory Service Package
The following MASM instructions illustrate how the M$FDSP can be used:
$INCLUDE ‘MAXR$/’
$ASCII
$(2)
FNCT $EQU 0
VALUE + 0
BUFFER $RES 4400
BUFFLN $EQU $-BUFFER
$(1)
START .
DL A0,($CFS(‘MFD ‘))
DS A0,BUFFER
M$FDSP,‘CB’ BUFFLN,BUFFER,0
J MFDERR
M$FDSP,‘CB’ BUFFLN,BUFFER,FNCT
J MFDERR
LXI,U X11,0
LXI,U A0,BUFFLN
LXM,U A0,BUFFER
M$FDSP ,, VALUE
J MFDERR
J DONE
MFDERR .
L$SNAP ‘MFDERR’,2,0,0
DONE .
ER EXIT$
$END START
The structure of the MFD is described in the Exec Administration Reference Manual.
Every filename has a lead item entry in the MFD. For every F-cycle of that particular
filename, a main item entry exists. The lead item contains links to all the main items,
and it can be up to two sectors, sector 0 and sector 1. If there are more main items than
sector 0 can hold links to, a sector 1 of the lead item will contain the links to the rest of
the main items. To access all possible main items in the MFD, you must use the
following algorithm:
Call MFDSP$ specifying function 0 to initialize and get
the first lead item.
GETNEXTMAIN:
Call MFDSP$ specifying function 4, (Get-Next-Main-Item),
and continue calling Get-Next-Main-Item until a
No-Find condition (A1=0) occurs.
Call Get-Sector-1-of-Lead-Item (MFDSP$ function 3).
IF a No-Find condition (A1=0) occurs, jump to GETNEXTLEAD.
Call Get-Next-Main-Item and continue to call it until a
No-Find condition occurs (A1=0).
GETNEXTLEAD:
Call Get-Next-Lead-Item (MFDSP$ function 2).
IF a No-Find condition (A1=0) occurs, exit the program,
OTHERWISE jump to GETNEXTMAIN.
7833 1733–004 13–9

MFDSP$–Master File Directory Service Package
A sample MASM program was developed which performs the preceding algorithm. It is
designed to be called only once.
.
. A program to access all the main items in the Master File Directory
.
INCLUDE ‘MAXR$’
$(1)
START* .
LA,U A0,MFDPKT . Call ER MSCON$ to acquire a
ER MSCON$ . copy of the directory
SA A0,STATWORD .
TZ,S3 STATWORD . Was MSCON$ erroneous?
J ERROR . YES, exit with error
DIROK .
LA A0,(4400,DSPPKT) . Call MFDSP$ function 0 to
LA,U A1,0 . initialize for DGET$ file
LMJ X11,MFDSP$ . and return the address of
. of the first lead item.
J ERROR . A 0,X11 return means error.
SZ A4 . Set a flag showing we have
. not gotten lead item sector 1.
NXTMAIN .
LA A0,(4400,DSPPKT) . Call MFDSP$ function 4
LA,U A1,4 . (Get Next Main Item).
LMJ X11,MFDSP$ .
J ERROR . A 0,X11 return means error
JZ A1,NOSNAP . IF A1=0, no Main Item found
SA A0,SNAPPKT+2 . ELSE, print out sector 0 of
SA,H2 A1,SNAPPKT+1 . the main item
LA,U A0,SNAPPKT .
ER SNAP$ .
NOSNAP .
TZ A1 . Was a Main Item found?
J NXTMAIN . Yes, get the next one.
TNE,U A4,1 . Have we already gotten
. sector 1 of the lead item?
J NEXTLEAD . YES, get the next lead item
LA,U A4,1 . NO, set the flag to show
. we’re getting sector 1 now.
LA A0,(4400,DSPPKT) .
LA,U A1,3 . Get sector 1 of lead item.
LMJ X11,MFDSP$ .
J ERROR . A 0,X11 return means error
JZ A1,NOSNAP3 . IF A1=0, no find occurred.
SA A0,SNAPPKT3+2 . ELSE, print out sector 1 of
SA,H2 A1,SNAPPKT3+1 . the current lead item.
LA,U A0,SNAPPKT3 .
ER SNAP$ .
13–10 7833 1733–004

MFDSP$–Master File Directory Service Package
NOSNAP3 .
TZ A1 . Did we find a sector 1?
J NXTMAIN . YES, get more main items
NEXTLEAD .
SZ A4 . Set the flag showing we have
. not gotten lead item sect 1.
LA A0,(4400,DSPPKT) . (We’re getting the next lead
LA,U A1,2 . item now.)
LMJ X11,MFDSP$ .
J ERROR . A 0,X11 return means error
JZ A1,EXIT . IF A1=0, no find occurred.
SA A0,SNAPPKT2+2 . ELSE print out sector 0 of
SA,H2 A1,SNAPPKT2+1 . the lead item.
LA,U A0,SNAPPKT2 .
ER SNAP$ .
J NXTMAIN . Get the next main item.
ERROR .
L$SNAP ‘ERROR’,2 . An error occurred. ABORT.
ER EABT$ .
EXIT .
er exit$ . exit the program.
$(0) .
SNAPPKT + ‘MAIN’ . The Main Item SNAP packet
+ 0200034000000 . Snap A-registers, 034 words,
+ 0 . start address gets filled in
. in the code.
SNAPPKT2 + ‘LEAD0’ . The Lead Item sector 0 SNAP
+ 0200034000000 . packet
+ 0 .
SNAPPKT3 + ‘LEAD1’ . The Lead Item sector 1 SNAP
+ 0200034000000 . packet
+ 0 .
STATWORD $RES 1 .
MFDPKT + 015 . The packet needed for
+ ‘TDIR$’ . calling ER MSCON$
+ 900 .
+ MFDBUF1,MFDBUF2 .
+ 0 .
MFDBUF1 $RES 1792 .
MFDBUF2 $RES 1792 .
DSPPKT + ‘TDIR$’ . The packet needed for
$RES 4398 . calling MFDSP$.
$END START .
7833 1733–004 13–11

MFDSP$–Master File Directory Service Package
13–12 7833 1733–004

Section 14
PREPRM, PREPRO, PREPF$, and
POSTPR$
PREPRM, PREPRO, and PREPF$ are preprocessor routines; POSTPR$ is a
postprocessor routine. The preprocessor routines assign input and output files to a
processor. The postprocessor routine frees files that were assigned by a preprocessor
routine.
14.1. PREPRO, PREPRM–Preprocessor Routines
PREPRO is designed for use by processors that require three fields on the processor call
statement. The processor calling PREPRO can use up to the maximum 63 fields but
PREPRO will only process the first three fields. Some of the OS 2200 processors that
use PREPRO are ACOB, Collector (MAP), FTN, LINK, and MASM.
PREPRM is designed for use by processors that require two fields on the processor call
statement. The processor calling PREPRM can use up to the maximum 63 fields but
PREPRM will only process the first two fields. Two of the OS 2200 processors that use
PREPRM are ELT and PDP.
See the ECL and FURPUR Reference Manual for a complete description of the processor
call statement. The general format of the processor call statement is
@[label:]processor[,options] field-1,field-2,field-3,...,field-n
PREPRO dynamically attaches internal filenames to the filenames specified in the first
three fields as follows: SI$$ is attached to field-1, RO$$ is attached to field-2, and SO$$
is attached to field-3. Therefore, field-1 is commonly referred to by the mnemonic SI,
field-2 as RO, and field-3 as SO.
field-1 (SI) is expected to contain the symbolic input to the processor. PREPRO checks
that the element specified is typed as symbolic (element type 01).
field-2 (RO) is expected to contain an output element and may be used for executable,
object module, omnibus, relocatable, or symbolic output. If the Relocatable Output
Routine (ROR) will be used, then field-2 (RO) specifies the relocatable output element.
field-3 (SO) is typically used for the updated symbolic output element if corrections are
applied to the input symbolic element in field-1 (SI). If the Symbolic Input/Output
Routine (SIR$) will be used then field-3 (SO) specifies the symbolic output element.
7833 1733–004 14–1

PREPRM, PREPRO, PREPF$, and POSTPR$
PREPRM dynamically attaches internal filenames to the filenames specified in the first
two fields as follows: SI$$ is attached to field-1 and SO$$ is attached to field-2.
field-1 (SI) is expected to contain the symbolic input to the processor. PREPRM checks
that the element specified is typed as symbolic (element type 01).
field-2 (SO) is typically used for the updated symbolic output element if corrections have
been applied to the input symbolic element in field-1 (SI). This would apply if the routine
SIR$ will be used. However, field-2 (SO) may be used for other types of output
elements.
The mnemonics SI, RO, and SO appear in error messages output by PREPRO and
PREPRM. They refer to the first three fields on the processor call statement as follows:
SI field-1
RO field-2
SO field-2 if PREPRM is used; field-3 if PREPRO is used
14.1.1. PREPRO–Preprocessor Routine
PREPRO reads the processor call statement in internal format (INFOR) (see Section 12),
standardizes its form in PARTBL (see Figure 14-1), and dynamically assigns the
necessary files. PREPRO obtains the “next write location” for program files and, for
tape files, verifies that the source input element exists.
Initial Conditions
The processor must call PREPRO before it executes any read command such as
ER SYMB$ (READ$ function), ER AREAD$, or ER READ$.
The parameter table PARTBL must be externally defined and at least 40 words long. It
also should be zero-filled.
Calling Sequence
LMJ X11,PREPRO$
error return
normal return
Error Return
The error return is taken under the following conditions:
I/O error occurs (A0 = 0)
error when reading INFOR (A0 ≠ 0)
tape positioned improperly (A0 ≠ 0)
file does not exist (A0 ≠ 0)
file is not a program file (A0 ≠ 0)
14–2 7833 1733–004

PREPRM, PREPRO, PREPF$, and POSTPR$
The PARTBL that the calling program provides is filled with the data that is necessary to
process the files. The input/output files are assigned as follows:
SI assigned
RO assigned exclusively
SO assigned exclusively
If SI is the same file as RO or SO, it is assigned exclusively.
14.1.2. PREPRM–Preprocessor Routine
PREPRM generates the source input and source output fields of PARTBL
(see Figure 14-1). It performs dynamic assigns and program file searches on the source
input and source output files.
Initial Condition
PARTBL must be externally defined and 27 words long (or 40 words long if relocatable
output field is needed). It should be zero-filled.
Calling Sequence
LMJ X11,PREPRM$
error return
normal return
The information on the processor call statement is transferred to PARTBL (see Figure
14–1).
The input/output files are assigned as follows:
Symbolic input assigned
Symbolic output assigned exclusively
If the symbolic input file is the same file as the symbolic output file, the symbolic input
file is assigned exclusively.
On error return, an error message is printed.
The PREPRO and PREPRM automatically fill PARTBL fields when called. The fields are
filled with data needed by the SIR$, ROR, SOR, and POSTPR$ routines of SYSLIB.
7833 1733–004 14–3

PREPRM, PREPRO, PREPF$, and POSTPR$
Figure 14–1. PARTBL Table Format
14–4 7833 1733–004

14.1.3. PARTBL Description
PREPRM, PREPRO, PREPF$, and POSTPR$
PARTBL is generated by the SYSLIB preprocessing routines (PREPRO, PREPRM, or
PREPF) and provides file information to SIR$, ROR, SOR, and POSTPR$. This
information includes the file/element name, cycle, size, and location of elements. All file,
element, and version names are left-justified and space-filled.
The internal filenames are use-names that have been dynamically attached to the
external filenames on the processor call statement by the PREPRM, PREPRO, and
PREPF$ routines. The internal names in PARTBL can be as follows:
Field Processor Call
PREPRO PREPRM PREPF$
Field 1 SI$$ SI$$ SI$
Field 2 R0$$ SO$$ SO$
Field 3 SO$$
The mnemonics refer to
SI symbolic input
SO symbolic output
RO resultant output
The default file name is TPF$. NAME$ is the default element name.
Word 0
input file type
0 Input from runstream
050 Program file
076 Tape file
options
Words 3–12
Option letters are A through Z left to right; for example, if the Z option is
specified, bit 35 is set to 1.
Contain the symbolic input element table item in the program file table of contents.
7833 1733–004 14–5

PREPRM, PREPRO, PREPF$, and POSTPR$
Word 13
file information
Contains indicators that the routine POSTPR$ uses to restore program files to
their original assignment state.
S1 Source input
S2 Source output
S3 Relocatable output
0 No action
1 @FREE,A remove attached name (SI$, SO$, RO$)
2 @FREE,AX remove attached name and release exclusive use
3 @FREE,AR remove attached name and free file
010 File is read inhibited
020 File is tape
040 Write permission denied
ITI–input termination indicator
Contains the SIR$ input termination indicator for purposes of processor
reusability. The possible values are
0
1
2
Reuse of the processor is possible. (Input terminated by call to CLOSR$, or
@EOF image, end of @ADD,E file, INFOR CLIST image, or transparent
control image.)
End of file has been encountered. (Symbiont read operation returned with
bit 0 set in register A0.)
requested cycle
@ENDX has been encountered.
Contains source input element cycle requested. If none requested, the latest
cycle is used.
Words 16–25
Contain the symbolic output element table item.
14–6 7833 1733–004

Words 27–39
May also be used for source output, that is, with SOR.
Words 29–38
Contain the relocatable element table item.
14.1.4. Reusable Processor Construction
PREPRM, PREPRO, PREPF$, and POSTPR$
Initial program load operations are expensive relative to swapping. A mechanism is
provided that allows a program to make itself reusable, thereby avoiding the need to
reload itself. This applies to programs called by processor call statements but not by
@XQT. If the processor in question makes use of the standard processor interface
routines (PREPRO, PREPRM, POSTPR$, ROR, SOR, SIR$), implementing reusability is
not a major task. The following describes the appropriate steps.
1. Register the processor name with INFOR CLIST (ER CLIST$), either ASCII or
Fieldata. Use a type 0 list, because an unknown control statement terminates CLIST
mode. See the Exec ER Programming Reference Manual.
2. Become self-initializing or self-reinitializing. This means that any data areas that are
expected to contain particular values at the beginning of the program must be
initialized by a particular instruction sequence. Do not rely on static data initialization.
Do this by explicitly setting all initialized variables to their initial value or by reloading
the main segment. The former method is recommended unless the number of
variables is excessive.
3. Check for potential reusability as indicated in PARTBL by SIR$ (S4 of PARTBL+13;
see Figure 14–1); then call REPRO$ or REPRM$ to read the next INFOR, if any;
reinitialize or terminate depending on which return is given by REPRO$/REPRM$.
This is done with the following steps:
a. If S4 of PARTBL+13 > 0, call POSTPR$, then quit.
b. Zero INFOR$ (see Section 12), then call REPRO$ or REPRM$, setting A0 as
desired.
c. If absolute-eof return, call POSTPR$, then quit.
d. If wrong CLIST value, take action as defined for the particular processor in
question.
e. If error return, treat same as error return from PREPRO or PREPRM.
f. If normal return, reinitialize the processor (and SIR$, if used, by storing 0 in
SIRP2$); begin new processing operation (compilation, assembly, and so on).
7833 1733–004 14–7

PREPRM, PREPRO, PREPF$, and POSTPR$
14.1.4.1. REPRO$–Reusable Processor Preprocessor Routine
REPRO$ reads INFOR from the INFOR CLIST processor call statement. INFOR$ must
be set to zero. REPRO$ also performs some of the same functions as PREPRO.
Initial Conditions
The calling program must establish an INFOR CLIST. On completing SIR$, S4 of
PARTBL+13 must be zero.
PARTBL must be externally defined and at least 40 words long.
Calling Sequence
LA A0,expected-CLIST-index-or-zero
LMJ X11,REPRO$
absolute-eof return
wrong-CLIST-index return
error return
normal return
Returns
error
normal
Identical to those for PREPRO$.
absolute-eof
Indicates that an end-of-file condition has been encountered that cannot be
bypassed; that is, a nontransparent control statement or @ENDX was encountered.
In this case, the processor cannot reuse itself and must terminate.
wrong-CLIST-index
The wrong-CLIST-index return is optional for processors that have more than one
item in their INFOR CLIST and only want to analyze one specific command
automatically; the command is specified by its CLIST index given in A0 prior to
calling REPRO$. This return never occurs if A0 is zero on entry to REPRO$.
After the wrong-CLIST-index return, X11 points to a reentry location you want to
continue with the preprocessor routine. (Note that the CLIST index encountered is
found in S3 of INFOR$+1.) Use the following instructions:
LMJ X11,0,X11
error return
normal return
The two returns are the same as for PREPRO$.
14–8 7833 1733–004

PREPRM, PREPRO, PREPF$, and POSTPR$
14.1.4.2. REPRM$–Reusable Processor Preprocessor Routine
REPRM$ reads INFOR from the INFOR CLIST processor call statement; INFOR$ must
be set to zero. The other functions of REPRM$ are the same as for PREPRM, except
the reentry feature of REPRM.
Initial Conditions
The calling program must establish an INFOR CLIST. On completing SIR$, S4 of
PARTBL+13 must be zero.
PARTBL must be externally defined and at least 27 words long.
Calling Sequence
LA A0,expected-CLIST-index-or-zero
LMJ X11,REPRM$
absolute-eof return
wrong-CLIST-index return
error return
normal return
Returns
error
normal
Identical to those for PREPRM$.
absolute-eof
Indicates that an EOF condition has been encountered that cannot be bypassed; that
is, a nontransparent control statement or @ENDX was encountered. In that case,
the processor cannot reuse itself and must terminate.
wrong-CLIST-index
Is optional for processors that have more than one item in their INFOR CLIST and
only need to analyze one specific command automatically; this is specified by its
CLIST index given in register A0 prior to calling REPRM$. This return is never taken
if register A0 is zero on entry to REPRM$.
After the wrong-CLIST-index return, X11 points to a reentry location when the
preprocessor routine continues. (Note that the CLIST index is found in S3 of
INFOR$+1.)
Use the following instructions to reenter REPRM$:
LMJ X11,0,X11
error return
normal return
The two returns are the same as PREPRM$.
7833 1733–004 14–9

PREPRM, PREPRO, PREPF$, and POSTPR$
14.1.5. FLDGET–Processor Field Retrieval
The FLDGET routine retrieves individual fields from the processor call statement that
PREPRO or PREPRM do not process, such as field number 4 or higher if PREPRO is
being used and field number 3 or higher if PREPRM is being used.
Initial Conditions
FLDGETO$ and FLDGETM$ require PARTBL as defined for PREPRO and PREPRM,
respectively.
Calling Sequence
F66618 $FORM 6,6,6,18 . MASM form directive
F2466 $FORM 24,6,6
or
Parameters
Register A1
S5 of A1
ft
S6 of A1
fn
L A1,(F2466 0,ft,fn)
L A0,(F66618 0,n,m,j)
LMJ X11,FLDGETO$ (if using PREPRO$)
LMJ X11,FLDGETM$ (if using PREPRM$)
error return
normal return
field type of the field to be retrieved (see Field Type in Appendix G)
field number of the field to be retrieved (see Field Number in Appendix G)
14–10 7833 1733–004

Register A0
S2 of A0
S3 of A0
n
H2 of A0
m
j
control bits
Bit 11 (rightmost bit in S2 of A0)
Bit 10
Bit 9
if set, field will be used for output
if not set, field will be used for input
if set, do not allow tape for input
if not set, allow tape for input
PREPRM, PREPRO, PREPF$, and POSTPR$
if set, FLDGET does not print an error message when the specified field
cannot be found
if set, FLDGET prints all error messages
type of element (1 through 7); if field is intended to name an element in a
program file. Add 070 to element type if field is intended to name a file or
an element in a program file. Use 070 if field is intended to name a file only.
address of 13 word data area
Error Return
The error return is taken when
• The file cannot be assigned correctly.
• The input element cannot be found.
• A field is incorrectly coded.
• The specified field cannot be found. (A0 contains the same information SELT$
returned in A0 on a no find return.)
7833 1733–004 14–11

PREPRM, PREPRO, PREPF$, and POSTPR$
The information pertaining to the requested field is transferred from the INFOR table to
the 13-word data area specified by j. FLDGET assigns the files on the processor call line
if necessary. If elements are designated for input, then FLDGET verifies the existence of
the element. An internal file name of the form "Fxxyy$" is attached to each file, where xx
is the field type and yy is the field number. TPF$ is the default file.
The processor can request either a file or an element by adding 070 to the element type.
In other words, 077 in field m indicates an omnibus element or a file. The request for an
element has precedence over a request for a file.
The following describes how FLDGET uses the control bits of parameter n in register A0.
When bit 11 of parameter n is set (in other words, field is for output), FLDGET:
• Assigns file exclusively
• Does not allow tape files
• Stores the element name, version, and type in the 13-word data area
When bit 11 of parameter n is not set (in other words, field is for input), FLDGET
• Allows tape files (depending on bit 10 of parameter n)
• Stores the equipment code in S4 of the first word of the 13-word data area
• Does an ER PFS$ on the supplied information
• Checks element cycling; relative cycling is allowed
When bit 9 of parameter n is set, error message printing is suppressed and the first
word of the 13-word data area is set to negative if the specified field cannot be found.
All other error messages are printed.
14.2. PREPF$–Preprocessor Routine
PREPF$ generates the source input and source output fields of PARTBL (see
Figure 14–1). PREPF$ also performs dynamic assigns of source input and output files if
they are not already assigned. This routine is intended for processors that use files
rather than elements. The input or output file may be a tape file, a temporary file, or a
cataloged file.
PREPF$ is for processors that require two fields on the processor call statement and use
files instead of elements. The files can be tape files, temporary files, or cataloged files.
The processor calling PREPF$ can have a maximum of 63 fields, but PREPF$ will only
process the first two fields. The two fields are processed as the source input file and/or
the source output file depending on the option field on the processor call statement.
PREPF$ performs dynamic assigns of the files if they are not aleady assigned, and
attaches internal file names as follows:
$SI is attached to the source input file.
$SO is attached to the source output file.
14–12 7833 1733–004

PREPRM, PREPRO, PREPF$, and POSTPR$
PREPF$ generates the source input and source output fields of PARTBL (see Figure
14–1).
Initial Condition
PARTBL must be externally defined, and at least 27 decimal words in length, and should
be zero-filled.
Calling Sequence
LMJ X11,PREPF$
error return
normal return
PREPF$ transfers information from the source input and source output parameters of
the processor call line to PARTBL. The options specified on the processor call statement
control how the information is placed in PARTBL. The options and associated results are
as follows:
• No options
− If only the SI field is given, it is assumed to be the output file.
− If only the SO field is given, an error message is printed and the error return is
taken.
− If both SI and SO fields are given, the files are assigned.
− If the SI and SO fields are not given, the PARTBL internal filename for SI and SO
is set to 12 fieldata space characters, and a normal return to the user is taken.
• I option
− SI field is assumed to be the output file.
− If the SO field is given, an error message is printed and the error return is taken.
− If the SI and SO fields are not given, the PARTBL internal file name for SI and SO
is set to 12 Fieldata space characters, and a normal return to the user is taken.
• U option
− If the SI field is not given, an error message is printed and the error return taken.
− If the SO field is given, an error message is printed and the error return taken.
− The U option implies that the next higher F-cycle of the SI file is to be produced.
The SI file must be a cataloged or temporary file. The SI (+1) file must be
assigned to the run. The name specified in the SI field cannot be a use name.
The error return is taken if PREPF$ receives a nonzero status code from a call to ER
CSF$.
7833 1733–004 14–13

PREPRM, PREPRO, PREPF$, and POSTPR$
14.3. POSTPR$–Postprocessor Routine
POSTPR$ removes all changes in the assignment status of a file that PREPRO,
PREPRM, or PREPF$ made.
Calling Sequence
LMJ X11,POSTPR$
error return
normal return
All files specified on the processor call statement are restored to the status they had
before the processor call.
The error return is taken if POSTPR$ receives a nonzero status code from a call to ER
CSF$.
14.4. FLDREL$–Field Release
FLDREL$ removes changes in the assignment of program files that were made by
FLDGETO$ or FLDGETM$.
Calling Sequence
L,U A0,address
LMJ X11,FLDREL$
error return
normal return
where address is the address of the data area given to FLDGET$.
Using the information saved in the first three words of the data area pointed to by
address, the file is restored to the state it was in before FLDGET$ was called.
The error return is taken if the free returns a negative status.
14–14 7833 1733–004

Section 15
ROR, ROR$–Relocatable Output Routine
The Relocatable Output Routine produces a relocatable element that is used for input to
the Collector. The relocatable element is produced from relocatable items the language
processors generate.
The Relocatable Output Routine contains user interfaces SROR$, ROR$, EROR$, and
TBLWR$. The following subsections describe these interfaces. Do not call the
Relocatable Output Routine from a minor register set activity.
If the external buffer version of ROR (ROR$) is used, ($EB entry points) then the $EB
entry points must be used for all calls to ROR. These entry points are: SROR$EB,
ROR$EB, EROR$EB, and TBLWR$EB.
15.1. SROR$, SROR$EB–Start Relocatable Output
Routine
SROR$ initializes ROR prior to writing any relocatable text words.
Calling Sequence
L,U A0,K-bit limit
LMJ X11,SROR$
error return
normal return
Parameters
K-bit limit
The number of bits required to contain either the largest control counter or the
number of undefined symbols for the relocation, whichever is larger.
SROR$ saves the K-bit limit for the relocatable element and establishes the program file
write location for the element via ER PFWL$. (See the Exec ER Programming Reference
Manual.) SROR$ adjusts the output buffer to minimize read-before-write operations,
if possible.
7833 1733–004 15–1

ROR, ROR$–Relocatable Output Routine
Error Return
The error return occurs when a nonzero status code is encountered in register A2.
Register A2 contains the status code from ER PFWL$. (See the Exec ER Programming
Reference Manual.)
The calling parameters for SROR$EB differ from SROR$ by the addition of a parameter
that defines the external buffer to be used by ROR$. The length and address of the
buffer are provided by the caller in H1 and H2 of register A1, respectively. All other
parameters for SROR$EB are unchanged. A buffer length of at least 1792 words
(1 track) is recommended.
Calling Sequence (External Buffer)
L,U A0,K-bit limit
L A1,(length-of-buffer,address-of-buffer)
LMJ X11,SROR$EB
error return
normal return
Parameters
length-of-buffer
The number of words in buffer. Must be a multiple of 112 words (4 sectors).
A minimum buffer length of 1792 words (1 track) is recommended.
address-of-buffer
Address of the buffer in caller's data area.
15.2. ROR$, ROR$EB–Generation of Relocatable
Output
ROR$ formats relocatable items and outputs text to the relocatable element.
Calling Sequence
L,U A0,address-of-item
LMJ X11,ROR$ (or ROR$EB)
error return
normal return
Error Return
The error return is taken when
• An I/O error occurs; A1 will contain the status.
• An internal inconsistency occurred in ROR; A1 will be zero.
15–2 7833 1733–004

Item Description
ROR, ROR$–Relocatable Output Routine
ROR is called for every text word that will be inserted into the relocatable element.
(Examples of text words are the instruction or data word.) For each call, the calling
program must supply the text word and its relocation information in an item.
The minimum length of the item is three words; however, it may be larger. Any
relocation of a text word, other than a simple relocation of the right address under the
same location counter that applies to the text word, must be handled through special
relocation items. Any number of special relocation items may be appended to the item.
Figure 15–1 shows the ROR item format.
0 n not used l r
1 text word
2 f zero lc address
special relocation items
.. . . .
n-1 special relocation items
Field Descriptions
Word 0
n
l
r
Figure 15–1. ROR: Item Format
Item length, including any special relocation items.
Bits 16 and 17 of a left address field plus 10 sign bits, or 12 sign bits, for a left
half-word field.
Bits 16 and 17 of a right address field plus 10 sign bits, or 12 sign bits, for a right
half-word field.
7833 1733–004 15–3

ROR, ROR$–Relocatable Output Routine
Word 1
text word
Word 2
f
lc
Bit 3 = 1, right address (bits 20-35) relocatable.
Bit 2 = 1, left address (bits 2-17) relocatable.
Contains the location counter the text word is under, and by which relocation
specified by f takes place. May be overridden by a type 013 special item.
address
Address of the text word.
Words 3, 4, and so on, may contain special relocation items.
Location Counter Formats
Following are descriptions of the three types of location counters.
• The Location Counter Relocation Item, type 011, is used for relocation by a location
counter other than the one specified in S3 of word 2.
The format is
01 011 l r lc
where:
l
r
lc
The left margin of the field of relocation (a bit number in the range 0–35).
The right margin of the field of relocation (a bit number in the range 0–35,
with r less than or equal to l).
Location counter number; a signed 12-bit integer. The starting address of the
location counter is added if lc is positive or subtracted if lc is negative.
15–4 7833 1733–004

ROR, ROR$–Relocatable Output Routine
• The External Reference Item (two words), type 012, is used for relocation by the
value of an externally defined symbol.
The format is
02 012 l r signs
where:
l
r
signs
sequence number of the external reference in the preamble
The left margin of the field of relocation.
The right margin of the field of relocation.
Twelve bits of all zeros or ones, depending on whether the external reference is
to be added or subtracted, respectively.
• The Large Location Counter Item, type 013, format is:
01 013 not used lc
where lc is the location counter number the text will be under.
If this special item is used, it must be the first special item appended to the item.
This item overrides the lc in Word 2 of the item. This allows location counters
greater than 63.
ROR formats the text words and the relocation information into blocks and writes the
blocks to the relocatable element.
7833 1733–004 15–5

ROR, ROR$–Relocatable Output Routine
15.3. EROR$, EROR$EB–End Relocatable Output
Routine
EROR$ terminates ROR after the last text word has been processed.
EROR outputs the last block built by ROR and generates a transfer image. The transfer
image is a special word group. The format is described in Section 5, “Relocatable Binary
(RB) Format” of the Data Structures Programming Reference Manual.
Calling Sequence
L A0,(transfer-addr,transfer-addr-lc)
LMJ X11,EROR$ (or EROR$EB)
error return
normal return
Note: If a transfer location is not specified, then A0 must be negative (for example, if
the element is a subroutine).
Parameters
transfer-addr
location of the first instruction to be executed in the main program.
transfer-addr-lc
location counter to which the address applies.
Error Return
The error return is taken when an I/O error occurs. The status is returned in A1.
15.4. TBLWR$, TBLWR$EB–Write Table to File
TBLWR$ writes the preamble constructed by the calling program to the program file that
contains the relocatable text. ROR must have already written the element text to the
program file, and EROR must have been called.
An ER PFI$ is done to update the file's table of contents.
The preamble consists of one to five tables. The entries in PARTBL+29 through 38
(see Figure 14–1) are updated to reflect the preamble length, preamble location, and the
element type (5 = relocatable). The format of the preamble is described in Section 5,
“Relocatable Binary (RB) Format” of the Data Structures Programming Reference
Manual.
15–6 7833 1733–004

Calling Sequence
L,U A0,preamble-addr
L,U A1,preamble-length
LMJ X11,TBLWR$ (or TBLWR$EB)
error return
normal return
Error Return
The error return is taken when
ROR, ROR$–Relocatable Output Routine
• An I/O error occurs. A1 will contain the status.
• An error occurs on the ER PFI$. A1 will equal 0 and A2 will be the status.
15.5. Optimization Information
ROR and the Collector are more efficient if the instructions and data are coded under
control of location counters one and two, respectively. ROR has less processing to do
and produces a more compact relocatable element. The Collector has a smaller bit
stream to analyze.
7833 1733–004 15–7

ROR, ROR$–Relocatable Output Routine
15–8 7833 1733–004

Section 16
SAR$–Symbolic Access Routines
The Symbolic Access Routines (SAR$) allow the calling program to read and write
system data format (SDF) files.
SAR$ has four main functions:
• READ
Read symbolic images from SDF files, SDF elements, the READ$ file, or an alternate
READ$ file.
• WRITE
Write symbolic images to SDF files, SDF elements, the standard PRINT$ file, the
standard PUNCH$ file, alternate PRINT$ files, or alternate PUNCH$ files.
• ATREAD
Write a symbolic image to the current output stream and read a symbolic image
from the current input stream.
• COM
Write a symbolic image to the operator's console and read a symbolic image from
the operator's console.
Symbolic images have traditionally been in the Fieldata, ASCII/ISO, or attributed
character data (ACD) character sets. Additional coded character sets (CCS) have now
been defined and are supported by the Symbolic Access Routines. A total of 63 CCSs
are currently defined. Forty of these are referred to as ASCII-like. This means that the
character set is essentially identical to the ASCII/ISO character set in the octal range 000
through 0177, with any differences being minor. Refer to the ER Programming
Reference Manual, Table 14–1, for a detailed description of the CCSs. Throughout
Section 16, wherever ASCII or ASCII/ISO is used, the SAR$ capabilities apply equally to
all ASCII-like character sets.
The SAR$ functions may be called from either PLUS or MASM programs. These
functions are described in the following subsections.
SAR$ is available in relocatable elements and in the SYSLIB common banks. The READ,
ATREAD, and COM functions are in the common bank absolute SYSLIB$3. The WRITE
function is in the common bank absolute SYSLIB$4. Appendix E lists the relocatable and
common bank entry points for SAR$.
7833 1733–004 16–1

SAR$–Symbolic Access Routines
16.1. File Information Packet
The file information packet (FIP) is used to pass information to the Symbolic Access
Routines (SAR$) for input and output to SDF files, SDF elements, and alternate symbiont
files. The SAR$ calling program must supply the D-bank storage space for the FIP.
The file information packet is not required for reading from or writing to the standard
symbiont (READ$ and PRINT$) files.
All required information is placed in the FIP, and the address of the FIP is placed in the
SAR$ READ or WRITE packets.
16.1.1. PLUS Interface
The type definition for the FIP is contained in the PLUS definition element
SAR$FILEPKTD in the SYSLIB file SYS$LIB$*SYSLIB and may be obtained with the
PLUS COPY statement “COPY ('SAR$FILEPKTD');”. The identifier of the FIP data
structure type is SAR_FILE_INFO_PACKET. The length of the FIP is equal to the
constant SAR_FILE_INFO_PACKET_WORD_LENGTH defined in the element
SAR$FILEPKTD (current length is nine words). SAR_FILE_INFO_PACKET is defined as
LOCATABLE.
16.1.1.1. FIP Field Descriptions
The following fields of the FIP are set by the calling program:
PACKET_VERSION
PLUS Attribute: 6-bit integer
The FIP data structure version. The current version is equal to the constant
SAR_FILE_INFO_PACKET_CURRENT_VERSION defined in the element
SAR$FILEPKTD.
ACCESS_TYPE
PLUS Attribute: 6-bit status
The type of input being accessed
S'SDF_file' Input is from an SDF file.
S'SDF_element' Input is from an SDF element.
S'PROC' Input is from a PLUS, FORTRAN, or COBOL PROC.
S'Alternate_symbiont' Input is from an alternate READ file.
This field is set for input only; it is omitted for output. If input is from the runstream
(READ$ file), the FIP address in the READ packet is set to NULL.
16–2 7833 1733–004

PROC_CHARACTER_TYPE
PLUS Attribute: 6-bit status
The character set type of the PROC to be read
S'Fieldata' Fieldata 6-bit characters.
S'ASCII_ISO' ASCII/ISO 9-bit characters.
S'ACD' Attributed character data (ACD).
This field is defined only for the ACCESS_TYPE of S'PROC'.
PROC_SOURCE_LANGUAGE_TYPE
PLUS Attribute: 9-bit status
The source language type of the PROC to be read
SAR$–Symbolic Access Routines
S'PLUS' The source language type is PLUS.
S'FORTRAN' The PROC source language type is FORTRAN.
S'COBOL' The PROC source language type is COBOL.
This field is defined only for the ACCESS_TYPE of S'PROC'.
FILE_NAME_BUFFER_BYTE_LENGTH
PLUS Attribute: 9-bit integer
The length in bytes of the buffer containing the internal file name; legal values are
from 1 to 12 bytes. May be set to 12 if the file name is space-filled to 12 characters.
ELEMENT_NAME_BUFFER_BYTE_LENGTH
PLUS Attribute: 9-bit integer
The length in bytes of the buffer containing the output element name; legal values
are from 1 to 12 bytes. This field is set for output only; it is omitted for input. May
be set to 12 if the element name is space-filled to 12 characters.
VERSION_NAME_BUFFER_BYTE_LENGTH
PLUS Attribute: 9-bit integer
The length in bytes of the buffer containing the output version name; legal values are
from 1 to 12 bytes. This field is set for output only; it is omitted for input. May be
set to 12 if the version name is space-filled to 12 characters.
7833 1733–004 16–3

SAR$–Symbolic Access Routines
FILE_NAME_BUFFER_ADDRESS
PLUS Attribute: word pointer
The address of the buffer containing the internal file name. The file name must be in
the ASCII/ISO character set, with length from 1 to 12 characters.
ELEMENT_NAME_BUFFER_ADDRESS
PLUS Attribute: word pointer
The address of the buffer containing the output element name. The element name
must be in the ASCII/ISO character set, with length from 1 to 12 characters. This
field is used only for output and an OUTPUT_FILE_TYPE of S'SDF_element'.
VERSION_NAME_BUFFER_ADDRESS
PLUS Attribute: word pointer
The address of the buffer containing the output version name. The version name
must be in the ASCII/ISO character set, with length from 1 to 12 characters. This
field is used only for output and an OUTPUT_FILE_TYPE of S'SDF_element'.
ELEMENT_FLAG_BITS
PLUS Attribute: 12-bit logical
The element flag bits as defined in the Program File Element Table, Data Structures
Programming Reference Manual. This field is defined only if writing to an SDF
element.
ELEMENT_TYPE
PLUS Attribute: 6-bit integer
The symbolic element type; see the Data Structures Programming Reference
Manual for element type definitions. This field is defined only if writing to an SDF
element.
ELEMENT_SUBTYPE
PLUS Attribute: 6-bit integer
The symbolic element subtype; see 2.6 for element subtype definitions. This field is
defined only if writing to an SDF element.
16–4 7833 1733–004

ACTUAL_ELEMENT_CYCLE
PLUS Attribute: 6-bit integer
SAR$–Symbolic Access Routines
The absolute cycle number of the SDF element. This field is defined only if reading
from or writing to an SDF element. If reading from an SDF element and if the actual
element cycle is not known, set this field to 0‘77’ to read all nondeleted element
cycles.
HIGHEST_SECTOR_ADDRESS
PLUS Attribute: 24-bit integer
The highest mass storage sector address assigned to the SDF file used for input or
output. This field is not currently used.
NEXT_READ_SECTOR_ADDRESS
PLUS Attribute: 24-bit integer
The mass storage sector address of the SDF input file to begin reading at. This field
is not used for symbiont files.
WORD_OFFSET_INTO_READ_SECTOR
PLUS Attribute: 6-bit integer
The word offset into the mass storage sector address of the SDF input file to begin
reading at. This field is not used for symbiont files.
NEXT_READ_LOCATION
PLUS Attribute: word machine integer
A one-word combination of NEXT_READ_SECTOR_ADDRESS and
WORD_OFFSET_INTO_READ_SECTOR contained in bits 12 to 35 and in bits 0 to 5,
respectively. (Bit 0 is the leftmost bit of the word.)
NEXT_WRITE_SECTOR_ADDRESS
PLUS Attribute: 24-bit integer
The mass storage sector address of the SDF output file to begin writing at. This field
is not used for symbiont files.
WORD_OFFSET_INTO_WRITE_SECTOR
PLUS Attribute: 6-bit integer
The word offset into the mass storage sector address of the SDF output file to begin
writing at. This field is not used for symbiont files.
7833 1733–004 16–5

SAR$–Symbolic Access Routines
NEXT_WRITE_LOCATION
PLUS Attribute: word machine integer
A one-word combination of NEXT_WRITE_SECTOR_ADDRESS and
WORD_OFFSET_INTO_WRITE_SECTOR contained in bits 12 to 35 and in bits 0 to 5,
respectively. (Bit 0 is the leftmost bit of the word.)
16.1.1.2. READ and WRITE Field Requirements
FIP fields required for the READ and WRITE functions of SAR$ are as follows:
• Fields required for READ
PACKET_VERSION
ACCESS_TYPE
FILE_NAME_BUFFER_ADDRESS
FILE_NAME_BUFFER_BYTE_LENGTH
NEXT_READ_LOCATION
• Additional fields required for READ if the ACCESS_TYPE is S'SDF_element' or
S'PROC'
PROC_CHARACTER_TYPE
PROC_SOURCE_LANGUAGE_TYPE
ACTUAL_ELEMENT_CYCLE
• Fields required for WRITE
PACKET_VERSION
FILE_NAME_BUFFER_ADDRESS
FILE_NAME_BUFFER_BYTE_LENGTH
NEXT_WRITE_LOCATION
• Additional fields required for WRITE if the OUTPUT_FILE_TYPE is S'SDF_element'
ELEMENT_NAME_BUFFER_ADDRESS
ELEMENT_NAME_BUFFER_BYTE_LENGTH
VERSION_NAME_BUFFER_ADDRESS
VERSION_NAME_BUFFER_BYTE_LENGTH
ELEMENT_FLAG_BITS
ELEMENT_TYPE
ELEMENT_SUBTYPE
ACTUAL_ELEMENT_CYCLE
The information that is stored in the FIP may be obtained from PARTBL, the externalized
table produced by the preprocessor routines PREPRO and PREPRM.
16–6 7833 1733–004

16.1.2. MASM Interface
SAR$–Symbolic Access Routines
The S$ARFIPDEF PROC generates the EQUFs defining the packet fields of the file
information packet (FIP). The element SAR$PROCS contains this PROC. S$ARFIPDEF
also equates the current packet version and word length of the FIP to labels
FIP$CURVER and FIP$PWLEN, respectively. FIP$PWLEN is defined by the
S$ARFIPDEF PROC (current length is nine words).
Calling Format
S$ARFIPDEF x-reg,b-reg,dispflg
Parameters
x-reg
b-reg
dispflg
The X-register to be attached to the file information packet EQUFs. If it is omitted,
no X-register is attached to the EQUFs.
The B-register to be attached to the file information packet EQUFs. If it is omitted,
no B-register is attached to the EQUFs.
A flag to display a table of file information packet EQUFs. If it is set to 'D', the field
names are displayed. Otherwise the field names are not displayed.
Example
$ASCII
$INCLUDE ‘MAXR$’
S$ARFIPDEF X7,,‘D’
This PROC call generates the EQUFs using X7 and no B-register, and displays the file
information packet fields.
16.1.2.1. FIP Field Descriptions
The following fields of the FIP are set by the calling program:
FIP$VER
The FIP data structure version. The current version is equal to label FIP$CURVER,
defined by the S$ARFIPDEF PROC.
7833 1733–004 16–7

SAR$–Symbolic Access Routines
FIP$ACTYP
The type of input being accessed
0 Input is from an SDF file.
1 Input is from an SDF element.
2 Input is from a COBOL, FORTRAN, or PLUS PROC.
3 Input is from an alternate READ file.
This field is set for input only; it is omitted for output.
FIP$PCHAR
The character set type of the PROC to be read
0 Fieldata 6-bit characters.
01 ASCII/ISO 9-bit characters.
077 Attributed character data (ACD).
This field is defined only for the access type 2 (PROC).
FIP$PLANG
The source language type of the PROC to be read. For access type of PROC
1 The PROC source language type is COBOL.
2 The PROC source language type is FORTRAN.
4 The PROC source language type is PLUS.
This field is defined only for the access type 2 (PROC).
FIP$FNLEN
The length in bytes of the buffer containing the internal file name; legal values are
from 1 to 12 bytes. May be set to 12 if the file name is space-filled to 12 characters.
FIP$ENLEN
The length in bytes of the buffer containing the input or output element name; legal
values are from 1 to 12 bytes. May be set to 12 if the element name is space-filled
to 12 characters.
FIP$VNLEN
The length in bytes of the buffer containing the input or output version name; legal
values are from 1 to 12 bytes. May be set to 12 if the version name is space-filled to
12 characters.
16–8 7833 1733–004

FIP$FNBUF
SAR$–Symbolic Access Routines
The address of the buffer containing the internal file name. The file name must be in
the ASCII/ISO character set, with length from 1 to 12 characters.
FIP$ENBUF
The address of the buffer containing the output element name. The element name
must be in the ASCII/ISO character set, with length from 1 to 12 characters. This
field is used only for output and an output file type (SW$OUTFILT) of 0 (SDF
element).
FIP$VNBUF
The address of the buffer containing the output version name. The version name
must be in the ASCII/ISO character set, with length from 1 to 12 characters. This
field is used only for output and an output file type (SW$OUTFILT) of 0 (SDF
element).
FIP$EFB1
The first set of 6 element flag bits (12 total), corresponding to bits 0 to 5 of word 3 in
the Program File Element Table Item. See the Data Structures Programming
Reference Manual for further details. This field is defined only if reading from or
writing to an SDF element.
FIP$EFB2
Second set of 6 element flag bits, corresponding to bits 6 to 11 of word 3 in the
Program File Element Table Item. See the Data Structures Programming Reference
Manual for further details. This field is defined only if reading from or writing to an
SDF element.
FIP$ETYP
The symbolic element type; see the Data Structures Programming Reference
Manual. This field is defined only if reading from or writing to an SDF element.
FIP$ESTYP
The symbolic element subtype; see 18.3 for element subtype definitions. This field
is defined only if reading from or writing to an SDF element.
FIP$ECYC
The absolute cycle number of the SDF element. This field is defined only if reading
from or writing to an SDF element. If reading from an SDF element and if the actual
element cycle is not known, set this field to 0'77' to read all nondeleted element
cycles.
7833 1733–004 16–9

SAR$–Symbolic Access Routines
FIP$HSEC
The highest mass storage sector address assigned to the SDF file used for input or
output. This is a 24-bit field contained in bits 12 to 35 of the word (bit 0 is the
leftmost bit of the word). This field is not currently used.
FIP$NRSEC
The mass storage sector address of the input file to begin reading at. This field is a
full word; however, S1 contains the word offset (FIP$NRWO), which is not part of
the sector address. This field is not used for symbiont files.
FIP$NRWO
The word offset into the mass storage sector address of the SDF input file to begin
reading at. This field is equated to S1 of FIP$NRSEC, and must be set after
FIP$NRSEC is set. Otherwise it will be overwritten. This field is not used for
symbiont files.
FIP$NWSEC
The mass storage sector address of the SDF output file to begin writing at. This
field is a full word; however, S1 contains the word offset (FIP$NWWO) which is not
part of the sector address. This field is not used for symbiont files.
FIP$NWWO
The word offset into the mass storage sector address of the SDF output file to begin
writing at. This field is equated to S1 of FIP$NWSEC, and must be set after
FIP$NWSEC is set. Otherwise it will be overwritten. This field is not used for
symbiont files.
16–10 7833 1733–004

16.1.2.2. READ and WRITE Field Requirements
SAR$–Symbolic Access Routines
FIP fields required for the READ and WRITE functions of SAR$ are as follows:
• Fields required for READ
FIP$VER
FIP$ACTYP
FIP$FNBUF
FIP$FNLEN
FIP$NRSEC
• Additional fields required for READ if FIP$ACTYP is 1 or 2
FIP$PCHAR
FIP$PLANG
FIP$ECYC
• Fields required for WRITE
FIP$VER
FIP$FNBUF
FIP$FNLEN
FIP$NWSEC
• Additional fields required for WRITE if SW$OUTFILT is 0
FIP$VNBUF
FIP$EFB2
FIP$VNLEN
FIP$ETYP
FIP$ENBUF
FIP$ESTYP
FIP$ENLEN
FIP$ECYC
FIP$EFB1
7833 1733–004 16–11

SAR$–Symbolic Access Routines
16.2. SAR$ Internal Format
All of the SDF images handled by the SAR$ functions are placed in internal format.
Internal format provides a common means of handling SDF images in different formats
(nonshift coded, shift-coded, ACD, and so forth). The READ, ATREAD, and COM
functions of SAR$ return SDF images to the calling program in internal format.
The calling program must supply images that will be written out by the WRITE, ATREAD,
and COM functions of SAR$ in internal format.
Internal format consists of the character part and the attribute part.
The character part contains a sequential list of the actual characters contained in the
image. The character part contains no shift codes, attributes, or other special
information. The characters in the character part must be in the ASCII/ISO, ASCII-like, or
JIS-16 (kanji) character sets.
The attribute part contains the attributes that apply to the characters in the character
part. Each attribute is represented as a one-word entry in the attribute table, with the
format in Figure 16–1
index type value
0 17 18 26 27 35
Figure 16–1. SAR$: Attribute Table Entry
The index is an 18-bit integer that indicates the position of the character in the character
part to which this attribute applies. When reading and writing ACD images, the index
range begins with 1 and ends with n, where n is the last 9-bit byte in the character part.
(An index is in 9-bit byte granularity.) When reading and writing shift coded images, the
index range begins with 1 and ends with n + 1. In this case, an index value of n + 1
corresponds to a shift coded image that ends with a shift code and is not followed by
any additional characters. More than one attribute can have the same index. However,
indexes must be in nondecreasing order.
The type is a 9-bit octal value that describes the type of the attribute. The types that are
currently defined are as follows:
001 Reset all attributes to default values
002 The character set type
003 The width of the character
004 The height of the character
005 The horizontal spacing between characters (center to center)
Any number of attributes may apply to the same character.
The value is a 9-bit octal value that provides specific information for the attribute type.
These values are defined in the PLUS COPY element, ACD$VALUES. Table 16-1 lists
the possible values for attribute types.
16–12 7833 1733–004

Type
SAR$–Symbolic Access Routines
Table 16–1. SAR$: Attribute Types and Values
Value When
Reading/ Writing
Shift-coded Data
Value When Reading/
Writing ACD
Description
001 0 0 No value applies
002 01
020
003, 004 0
003
004
005
006
005 0
001
002
003
005
007
7833 1733–004 16–13
0
020
0
0106
0132
0170
0360
0
not applicable
0110
0220
0170
0140
ASCII/ISO or ASCII-like
JIS-16 kanji
Device-dependent default
Seven point
Nine point
Twelve point
Twenty-four point
Device-dependent default
2.5 cpi (characters per inch)
10 cpi
5 cpi
6 cpi
7.5 cpi
Once an attribute type and value are applied to a character in the character part, that
attribute type and value apply to all of the following characters in the character part.
The attribute type and value remain active until either another value for that attribute
type is applied or the end of the character part is reached. If several attributes with the
same types but different values apply to the same character, the last attribute value is
used.

SAR$–Symbolic Access Routines
16–14 7833 1733–004

Section 17
SAR$ READ
17.1. READ Function/PLUS Interface
The SAR$ READ procedures can be called directly from PLUS. These procedures are
• SAR_OPEN_INPUT
• SAR_READ
• SAR_CLOSE_INPUT
All SAR$ data structure definitions and procedure calls are contained in definition
elements. These definitions and procedures may be obtained with the PLUS COPY
statement.
17.1.1. READ Packet Data Structure Description
The SAR$ READ function requires a READ packet data structure for the
SAR_OPEN_INPUT, SAR_READ, and SAR_CLOSE_INPUT procedure calls.
The type definition for this data structure is contained in the element SAR$RPKTD in the
SYSLIB file (SYS$*RLIB$ or SYS$LIB$*SYSLIB) and may be obtained with the COPY
statement. The identifier for the READ packet data structure type is
SAR_READ_PACKET.
The calling program must provide storage space for the READ packet data structure plus
any necessary buffers and tables, since SAR$ does not have any D-bank storage.
The length of the READ packet is equal to the constant
SAR_READ_PACKET_WORD_LENGTH, defined in the element SAR$RPKTD
(current length is 36 words). SAR_READ_PACKET is defined as LOCATABLE.
The calling program places information in the READ packet data structure and passes the
address of the data structure to SAR$ through the procedure calls.
7833 1733–004 17–1

SAR$ READ
17.1.1.1. Required Information for READ Procedures
The calling program must set the following fields of the READ packet to appropriate
values.
PACKET_VERSION
PLUS Attribute: 6-bit integer
The READ packet data structure version. The current version is equal to the
constant SAR_READ_PACKET_CURRENT_VERSION defined in the element
SAR$RPKTD. The PACKET_VERSION must not be modified between calls to the
SAR$ READ routine.
INPUT_FILE_INFO_PKT_ADDRESS
PLUS Attribute: word pointer
The address of the input file information packet. This packet is supplied by the caller
(see 16.1). Set to NULL if input is from the runstream.
INPUT_BUFFER_ADDRESS
PLUS Attribute: word pointer
The address of the input buffer, used to read images from the input file or element.
This field is defined only if input is from an SDF file or element. It is omitted if input
is from the runstream or an alternate READ$ file. Subsection 17.1.2 describes the
input buffer.
INPUT_BUFFER_WORD_LENGTH
PLUS Attribute: 18-bit integer
The length in words of the input buffer. It must be of length (28* dpf * n), where
dpf is the disk prepping factor and n is a positive integer. This field is defined only if
input is from an SDF file or element. It is omitted if input is from the runstream or
an alternate READ$ file.
IMAGE_BUFFER_ADDRESS
PLUS Attribute: word pointer
The address of the input image buffer, into which SAR$ places individual images
from the input buffer. Subsection 17.1.2 describes the image buffer.
IMAGE_BUFFER_WORD_LENGTH
PLUS Attribute: 18-bit integer
The length in words of the input image buffer.
17–2 7833 1733–004

TEXT_BUFFER_ADDRESS:
PLUS Attribute: word pointer
SAR$ READ
The address of the input text buffer, into which SAR$ places the character text of
the image read. Subsection 17.1.2 describes the text buffer.
TEXT_BUFFER_BYTE_LENGTH
PLUS Attribute: 18-bit integer
The length in 9-bit bytes of the input text buffer.
ATTRIBUTE_TABLE_ADDRESS
PLUS Attribute: word pointer
The address of the input attribute table where SAR$ places the attributes describing
the character text of the image read. This field is undefined if the
ATTRIBUTE_TABLE_WORD_LENGTH is zero. Subsection 17.1.2 describes the
format of the attribute table.
ATTRIBUTE_TABLE_WORD_LENGTH
PLUS Attribute: 18-bit integer
The length in words of the input attribute table. A length of zero indicates there is
no input attribute table.
17.1.1.2. Optional Information for READ Procedures
The calling program may optionally set the following fields of the READ packet. The
default values are obtained by zero-filling the READ packet before placing any
information in the packet.
SELECT_LIST_ADDRESS
PLUS Attribute: word pointer
The address of the select list that specifies which attributes to return to the caller.
This field is undefined if SELECT_LIST_BYTE_LENGTH is zero. Subsection 17.1.2
describes the format of the select list.
SELECT_LIST_BYTE_LENGTH
PLUS Attribute: 18-bit integer
The length in 9-bit bytes of the select list. A length of zero indicates there is no
select list (default).
7833 1733–004 17–3

SAR$ READ
REQUEST_TYPE
PLUS Attribute: 6-bit status
The requested type of input:
S'Pass_embedded_KANJI'
Do not search for embedded shift-coded kanji in ASCII/ISO (default).
S'Translate_embedded_KANJI'
Search for any embedded shift-coded kanji in ASCII/ISO input, and convert it into
internal format (text part and attributes part). Subsection 16.2 describes internal
format.
LINE_NUMBER_FORMAT
PLUS Attribute: 6-bit status
The format of line numbers returned by SAR$ to the caller.
S'Use_input_numbers'
Use the line number type read with the input image; it may be either a CTS or
fractional line number (see LINE_NUMBER_TYPE in 17.1.1.3). If no line number
exists for the input image, SAR$ increments the last line number by 1. If the
input contains mixed LINE_NUMBER_TYPEs, the line number will be compared
to the previous line number, and if necessary, incremented. If the input does
not have any line numbers, SAR$ generates sequential line numbers with initial
value 1 and increment value 1 (default).
S'Generate_CTS'
SAR$ generates sequential CTS line numbers with an initial value of 10 and an
increment value of 10.
S'Generate_fractional'
SAR$ generates sequential fractional line numbers with an initial value of 10 and
an increment value of 10.
S'No_line_numbers'
No line numbers are returned to the caller.
17–4 7833 1733–004

UNTRANSLATE_MODE
PLUS Attribute: 6-bit status
The untranslate mode flag setting:
S'Off'
S'On'
SAR$ READ
An error is returned if SAR$ reads a character set type other than 00 (Fieldata),
01 (ASCII/ISO), 077 (ACD) (default), or ASCII-like.
All input is passed to the caller untranslated.
SDF_CONTROL_RECORDS_TO_PASS
PLUS Attribute: word logical
This field specifies which SDF control records to return to the caller. Bits 1 to 32
may be set by the caller, where bit 1 is the leftmost bit of the field. If bit n is set, the
control record type ( n-1 + 040) is returned to the caller. The image control word of
the control record is returned in SDF_IMAGE_CONTROL_WORD, and any data
words of the control record are returned in the text buffer. If this field is set to zero,
no control records are returned to the caller (default).
Note that the control record type 051 is not returned unless it is used to continue a
type 061 control record. Therefore, it is suggested that the caller specify that type
051 records be returned if type 061 records are desired, and vice-versa.
READ_ADDRESS_SECTOR
PLUS Attribute: 24-bit integer
The mass storage sector address of the next image to be read. This field is used if
the image to be read is not the next sequential image. If this field is set to zero, the
next sequential image is read (default). This field is undefined if the input is not from
an SDF file or element.
7833 1733–004 17–5

SAR$ READ
READ_ADDRESS_WORD_OFFSET
PLUS Attribute: 6-bit integer
The word offset into the mass storage sector address of the next image to be read.
This field is used if the image to be read is not the next sequential image. If this
field is set to zero, the next sequential image is read (default). This field is undefined
if the input is not from an SDF file or element.
READ_ADDRESS
PLUS Attribute: word machine integer
A one-word combination of the READ_ADDRESS_SECTOR and the
READ_ADDRESS_WORD_OFFSET fields, where these fields are contained in bits
13 to 36 and 1 to 6, respectively. (Bit 1 is the leftmost bit of the READ_ADDRESS
field.)
17.1.1.3. Information Returned by READ Procedures
The following fields of the READ packet contain values returned by the SAR$ READ
procedures to the calling program.
CALL_STATUS
PLUS Attribute: 18-bit status
The status of the current call to SAR_OPEN_INPUT, SAR_READ, or
SAR_CLOSE_INPUT. See Table 17–3 for an explanation of the READ procedure call
status codes. This field may also be referenced as an 18-bit logical field with label
CALL_STATUS_CODE.
SUB_STATUS_CODE
PLUS Attribute: 12-bit logical
This field contains additional information for particular CALL_STATUS codes.
IO_STATUS
PLUS Attribute: 6-bit status
The status of any I/O operations performed by the READ procedures. See
Table 17–4 for the I/O status lists. This field may also be referenced as a 6-bit logical
field with label IO_STATUS_CODE.
17–6 7833 1733–004

READ_STATUS_WORD
PLUS Attribute: word logical
A one-word combination of CALL_STATUS, SUB_STATUS, and IO_STATUS
contained in H2, T1, and S3, respectively.
SYMB_STATUS_WORD
PLUS Attribute: word logical
The status word returned from an ER SYMB$ request.
SAR$ READ
See SYMB$ section, Exec ER Programming Reference Manual for further details on
the ER SYMB$ status word.
RECOMMENDED_BUFFER_SIZE
PLUS Attribute: 18-bit integer
The recommended buffer or table size when an invalid length is specified or when
an overflow occurs.
TEXT_LENGTH_IN_BYTES
PLUS Attribute: 18-bit integer
The length in 9-bit bytes of the character text returned in the text buffer.
NUMBER_OF_ATTRIBUTES
PLUS Attribute: 18-bit integer
The number of attributes returned in the attribute table.
CHARACTER_TYPE
PLUS Attribute: 6-bit status
The character set type of the image returned to the caller:
S'Fieldata' Fieldata 6-bit characters
S'ASCII_ISO' ASCII/ISO 9-bit characters
S'ACD' Attributed character data (ACD)
A value of any ASCII-like character set type defined in Table H–1.
If UNTRANSLATE_MODE is set to S'Off', then any Fieldata images read are
translated to ASCII/ISO before they are returned to the caller. See 17.3 for details on
allowed input character set types.
7833 1733–004 17–7

SAR$ READ
CHARACTER_CODE
PLUS Attribute: 6-bit logical)
The character set type of the image returned to the caller after any translation:
0 Fieldata 6-bit characters
01 ASCII/ISO 9-bit characters
077 Attributed character data (ACD)
A value of any ASCII-like character set type in Table H–1.
If UNTRANSLATE_MODE is set to S'Off', then any Fieldata images read are
translated to ASCII/ISO before they are returned to the caller. See 17.3 for details on
allowed input character set types.
INPUT_CHARACTER_CODE
PLUS Attribute: 6-bit status
The character set type of the image in the source input file or element. Contains the
code type from the last 050 or 042 control record encountered in the input file or
element.
IMAGE_ADDRESS_SECTOR
PLUS Attribute: 24-bit integer
The mass storage sector address of the SDF image read. This field is undefined if
input is from the runstream or an alternate READ$ file.
IMAGE_ADDRESS_WORD_OFFSET
PLUS Attribute: 6-bit integer
The word offset into the mass storage sector address of the SDF image read. This
field is undefined if input is from the runstream or an alternate READ$ file.
IMAGE_ADDRESS
PLUS Attribute: word machine integer
This field is a one word combination of IMAGE_ADDRESS_SECTOR and
IMAGE_ADDRESS_WORD_OFFSET, contained in bits 13 to 36 and in bits 1 to 6,
respectively. (Bit 1 is the left-most bit of the field.)
17–8 7833 1733–004

LINE_NUMBER_TYPE
PLUS Attribute: 3-bit condition
The type of line number returned with the image read.
S'None'
S'CTS'
SAR$ READ
No line number was read from the input; an SAR$ generated line number is
returned. See LINE_NUMBER_FORMAT in 17.1.1.2.
A CTS line number is returned.
S'Fractional'
A fractional line number is returned.
LINE_NUMBER_INTEGER_PART
PLUS Attribute: word integer
The line number returned by SAR$. It may be a CTS line number, the integer part of
a fractional line number, or a generated sequential line number (see
LINE_NUMBER_TYPE).
LINE_NUMBER_FRACTIONAL_PART (1:4)
PLUS Attribute: four one-word integers
The fractional part of fractional line numbers returned by SAR$. Each word of the
array contains 10 digits of the fraction. This field is defined only if
LINE_NUMBER_TYPE is S'Fractional'.
SDF_IMAGE_CONTROL_WORD
PLUS Attribute: word logical
The image control word for the SDF record read. This field is defined only if input is
from an SDF file or element. If bit 1 of this field is set, a control record was read; if
bit 1 of this field is clear, a data record was read.
If a control record was read, SDF_IMAGE_CONTROL_WORD has three subfields
that are overlaid on SDF_IMAGE_CONTROL_WORD:
CONTROL_RECORD_TYPE
PLUS Attribute: 6-bit logical
The type of control record read (an octal code from 040 to 077).
7833 1733–004 17–9

SAR$ READ
CONTROL_RECORD_WORD_LENGTH
PLUS Attribute: 6-bit integer
The length in words of the control record read.
CONTROL_RECORD_CHAR_TYPE
PLUS Attribute: 6-bit status
The character set type of the control record, if applicable to this control record
type (see the CHARACTER_TYPE field).
If a data record was read, SDF_IMAGE_CONTROL_WORD has two subfields that
are overlaid on SDF_IMAGE_CONTROL_WORD.
DATA_RECORD_WORD_LENGTH
PLUS Attribute: 12-bit integer
The length in words of the data record read.
DATA_RECORD_CHAR_TYPE
PLUS Attribute: 6-bit status
The character set type of the data record, if applicable to this input file type (see the
CHARACTER_TYPE field).
See the Data Structures Programming Reference Manual on SDF image control words.
17.1.2. Buffers and Tables for PLUS READ Procedures
The SAR$ READ function requires that an input (I/O) buffer, an image buffer, a text
buffer, an attribute table, and a select list be supplied by the calling program.
• Input buffer
The input buffer is used to read from mass storage files. The calling program never
needs to access the input buffer, but it must provide it to SAR$. If the calling
program is using both the READ and WRITE functions of SAR$, then it cannot use
the same I/O buffer for both functions. The calling program must provide a separate
input and output buffer for each function.
• Image buffer
The image buffer is used to extract individual images from the input buffer. This
buffer is necessary because images can contain information other than characters,
such as attributes and ACD formats. The calling program never needs to access the
image buffer, but it must provide it to SAR$. The calling program using the READ
and WRITE functions can use the same image buffer for both functions.
17–10 7833 1733–004

SAR$ READ
• Text buffer
The text buffer is used to return the characters contained in the image to the calling
program. The characters are taken from the image buffer and placed sequentially in
the text buffer, regardless of the format of the original image or any attributes that
may apply to them. The text buffer provides one part of internal format (see 16.2).
The calling program using the READ and WRITE functions can use the same text
buffer for both functions.
• Attribute table
The attribute table is used to return to the calling program the attributes that apply to
the characters in the text buffer. Each attribute has a one-word entry in the attribute
table which follows the format in Figure 17–1.
index type value
0 17 18 26 27 35
Figure 17–1. SAR$: Attribute Table Entry
The attribute table provides the other part of internal format (see 16.2). If the images
read by SAR$ do not contain any attributes or if UNTRANSLATE_MODE is set to
S'On', then the attribute table may be omitted by setting
ATTRIBUTE_TABLE_ADDRESS to null (zero). The calling program using the READ
and WRITE functions can use the same attribute table buffer for both functions.
• Select list
The select list is used to determine which SAR$ attributes are returned to the calling
program. It contains a sequential list of attribute types that are returned. Attribute
types that are not on the select list are not returned. For example, if the calling
program wants attribute types 3, 4, and 5 returned, the first word of the select list
would be 003004005000. If the select list is omitted, all attribute types are returned
to the calling program.
The calling program must provide all buffers and tables. The type definitions for the
buffers and tables, and definitions for the default buffer and table lengths, are contained
in the element SAR$DEFN. SAR$DEFN is in the SYSLIB file (SYS$LIB$*SYSLIB) or
SYS$*RLIB$. This element is obtained with the COPY statement. These definitions
simplify the creation of required tables and buffers for the calling program.
7833 1733–004 17–11

SAR$ READ
The default buffer and table lengths are listed in Table 17–1.
Table 17–1. SAR$: PLUS READ Buffer and Table
Length Defaults
Identifier Value
SAR_IO_BUFFER_WORD_LENGTH 448
SAR_IMAGE_BUFFER_WORD_LENGTH 63
SAR_TEXT_BUFFER_BYTE_LENGTH 132
SAR_ATTRIBUTE_TABLE_WORD_LENGTH 40
SAR_SELECT_LIST_BYTE_LENGTH 4
The buffer and table type definitions are listed in Table 17–2.
Table 17–2. SAR$: PLUS READ Buffer and Table Type
Definitions
Identifier Type
SAR_IO_BUFFER 448 words logical locatable
SAR_IMAGE_BUFFER 63 words logical locatable
SAR_TEXT_BUFFER 132 ASCII characters locatable
SAR_ATTRIBUTE_TABLE 40 words logical locatable
SAR_SELECT_LIST 4 bytes logical locatable
The element SAR$DEFN also contains other definitions necessary to SAR$.
17.1.3. READ Procedures Called from PLUS
The procedures for the READ function are:
• SAR_OPEN_INPUT
• SAR_READ
• SAR_CLOSE_INPUT
The declarations for these procedures are contained in the element SAR$READ$DG, in
the SYSLIB file (SYS$LIB$*SYSLIB) or SYS$*RLIB$. This element may be obtained with
the COPY statement.
SAR$READ$DG contains all three procedure declarations. All of the READ procedure
modules are compiled with the G option, using the IBJ$ calling sequence.
17–12 7833 1733–004

17.1.3.1. SAR_OPEN_INPUT Procedure Call
SAR$ READ
The READ packet data structure must be initialized before any input images are read.
The SAR_OPEN_INPUT procedure performs the READ packet initialization.
Initial Conditions
The calling program sets the following parameters in the READ packet to appropriate
values before calling SAR_OPEN_INPUT:
• Required parameters (described in 17.1.1.1)
PACKET_VERSION
INPUT_FILE_INFO_PKT_ADDRESS
INPUT_BUFFER_ADDRESS
INPUT_BUFFER_WORD_LENGTH
IMAGE_BUFFER_ADDRESS
IMAGE_BUFFER_WORD_LENGTH
• Optional parameters (described in 17.1.1.2)
SELECT_LIST_ADDRESS
SELECT_LIST_BYTE_LENGTH
REQUEST_TYPE
LINE_NUMBER_FORMAT
UNTRANSLATE_MODE
SDF_CONTROL_RECORDS_TO_PASS
Note: It is recommended that the calling program zero-fill the READ packet before
placing any parameters in the packet.
Calling Format
PROCEDURE SAR_OPEN_INPUT
(READ_PACKET_ADDRESS: WORD MACHINE POINTER)
IMPORTED ('SAR$OPENI$PG');
Returns
SAR_OPEN_INPUT returns the initialization status in the packet in CALL_STATUS. If the
status is S'Normal', the initialization of the READ packet is successful. Otherwise an
error has occurred, and CALL_STATUS contains the status code. See 17.1.4 for a list of
the READ function status codes.
7833 1733–004 17–13

SAR$ READ
17.1.3.2. SAR_READ Procedure Call
The SAR_READ procedure obtains one image from the input and returns the character
text and attributes of the image to the calling program.
Initial Conditions
The calling program sets the following parameters in the READ packet to appropriate
values before calling SAR_READ:
• Required parameters (described in 17.1.1.1)
TEXT_BUFFER_ADDRESS
TEXT_BUFFER_BYTE_LENGTH
ATTRIBUTE_TABLE_ADDRESS
ATTRIBUTE_TABLE_WORD_LENGTH
• Optional parameters (described in 17.1.1.2)
SELECT_LIST_ADDRESS
SELECT_LIST_BYTE_LENGTH
READ_ADDRESS_SECTOR
READ_ADDRESS_WORD_OFFSET
Calling Format
PROCEDURE SAR_READ
(READ_PACKET_ADDRESS: WORD MACHINE POINTER)
IMPORTED ('SAR$READ$PG');
Returns
Each call to SAR_READ reads one image from the input and returns the character text in
the text buffer, the attributes in the attribute table, and other information in the READ
packet. SAR_READ does not space-fill the text buffer if the text length is shorter than
the text buffer length. If the character text is longer than the text buffer, SAR_READ
truncates the text to the length of the text buffer and returns an error status in
CALL_STATUS.
SAR_READ returns the calling status in the READ packet field CALL_STATUS. If the
status is S'Normal', then the read was successful.
The following fields contain information returned by SAR$ to the caller:
• Character text
SAR_READ returns the character text of the image read in the text buffer and the
character text length in TEXT_LENGTH_IN_BYTES. The length is in 9-bit bytes
(characters).
• Character type
The character set type of the image read is returned in the field CHARACTER_TYPE.
The octal code of the character set type is returned in the field CHARACTER_CODE.
17–14 7833 1733–004

SAR$ READ
• Attributes
If there are any attributes that apply to the character text, they are returned in the
attribute table. The number of attributes is returned in NUMBER_OF_ATTRIBUTES.
• Line number
CTS, fractional, and generated sequential line numbers are returned in the field
LINE_NUMBER_INTEGER_PART. Fractional line numbers are returned in the array
LINE_NUMBER_FRACTIONAL_PART (1:4). The line number type is returned in the
field LINE_NUMBER_TYPE.
• Image location
The mass storage sector address and word offset of the image read are returned in
the fields IMAGE_ADDRESS_SECTOR and IMAGE_ADDRESS_WORD_OFFSET,
respectively.
• Control word
The image control word for data or control records is returned in the field
SDF_IMAGE_CONTROL_WORD. If a control record was read, any data words of the
control record are returned to the caller in the text buffer.
If SAR_READ encounters an end-of-file condition, the CALL_STATUS field of the READ
packet is set to status S'End_of_file'.
If the status returned from SAR_READ is not S'Normal', then an error has occurred, and
CALL_STATUS contains the status code. See 17.1.4 for a list of READ function status
codes.
17.1.3.3. SAR_CLOSE_INPUT Procedure Call
The SAR_CLOSE_INPUT procedure closes the input operation, which must be done
when all input is completed.
Calling Format
PROCEDURE SAR_CLOSE_INPUT
(READ_PACKET_ADDRESS: WORD MACHINE POINTER)
IMPORTED ('SAR$CLOSI$PG');
Returns
SAR_CLOSE_OUTPUT returns the calling status in the READ packet field
CALL_STATUS. If the status is S'Normal', then the close was successful.
If the status returned from SAR_CLOSE_OUTPUT is not S'Normal', then an error has
occurred and CALL_STATUS contains the status code. See 17.1.4 for a list of READ
function status codes.
7833 1733–004 17–15

SAR$ READ
17.1.3.4. Example
The following example shows the SAR$ READ function in a PLUS program, reading SDF
input:
COPY (‘SAR$DEFN’);
COPY (‘SAR$RPKTD’);
COPY (‘SAR$READ$DG’);
COPY (‘SAR$FILEPKTD’);
DECLARE READ_PKT: SAR_READ_PACKET,
IO_BUF: SAR_IO_BUFFER,
IMAGE_BUF: SAR_IMAGE_BUFFER,
TEXT_BUF: SAR_TEXT_BUFFER,
ATTRIBUTE_TBL: SAR_ATTRIBUTE_TABLE,
FILE_PKT: SAR_FILE_INFO_PACKET;
.
.
.
READ_PKT.PACKET_VERSION:= SAR_READ_PACKET_CURRENT_VERSION;
READ_PKT.INPUT_FILE_INFO_PKT_ADDRESS:= LOC(FILE_PKT);
READ_PKT.INPUT_BUFFER_ADDRESS:= LOC(IO_BUF);
READ_PKT.INPUT_BUFFER_WORD_LENGTH:= SAR_IO_BUFFER_WORD_LENGTH;
READ_PKT.IMAGE_BUFFER_ADDRESS:= LOC(IMAGE_BUF);
READ_PKT.IMAGE_BUFFER_WORD_LENGTH:= SAR_IMAGE_BUFFER_WORD_LENGTH;
READ_PKT.TEXT_BUFFER_ADDRESS:= LOC(TEXT_BUF);
READ_PKT.TEXT_BUFFER_BYTE_LENGTH:= SAR_TEXT_BUFFER_BYTE_LENGTH;
READ_PKT.ATTRIBUTE_TABLE_ADDRESS:= LOC(ATTRIBUTE_TBL);
READ_PKT.ATTRIBUTE_TABLE_WORD_LENGTH:= SAR_ATTRIBUTE_TABLE_WORD_LENGTH;
.
.
.
SAR_OPEN_INPUT(LOC(READ_PKT));
IF READ_PKT.CALL_STATUS NE S’Normal’
THEN BEGIN
PROCESS_READ_ERROR;
RETURN;
END;
.
.
.
SAR_EOF:= FALSE;
WHILE NOT SAR_EOF DO
BEGIN
SAR_READ(LOC(READ_PKT));
CASEENTRY READ_PKT.CALL_STATUS
CASE S ‘End_of_file’ : SAR_EOF:= TRUE;
CASE S ‘Normal’ :
BEGIN
.
.
.
END;
17–16 7833 1733–004

CASE * :
BEGIN
PROCESS_READ_ERROR;
RETURN;
END;
ENDCASE;
END;
.
.
.
SAR_CLOSE_INPUT(LOC(READ_PKT));
IF READ_PKT.CALL_STATUS NE S ‘Normal’
THEN BEGIN
PROCESS_READ_ERROR;
RETURN;
END;
SAR$ READ
In this example, the COPY statement obtains the SAR$ definitions for the buffers and
tables, READ packet, READ procedures, and file information packet. The SAR$ data
structures are declared by using the definitions contained in elements SAR$DEFN,
SAR$RPKTD, and SAR$FILEPKTD.
The READ packet is initialized by assigning appropriate values to all necessary fields.
All other packet fields take the default values if the READ packet is zero-filled.
The SAR_READ_PACKET_CURRENT_VERSION constant is defined in the SAR$RPKTD
element. The buffer length constants are defined in the SAR$DEFN element.
The READ function is initialized by the calling SAR_OPEN_INPUT procedure, passing the
READ packet address as a parameter. If the CALL STATUS field of the READ packet
(returned by SAR$) is not status ‘Normal', the error is processed.
The SAR_READ procedure reads one SDF image at a time until an end-of-file condition or
an error occurs. When all images are read, the READ function is closed by calling the
SAR_CLOSE_INPUT procedure.
17.1.4. Status Lists for PLUS READ Procedures
The READ procedure call status codes listed in Table 17–3 may be returned to the caller
in the CALL_STATUS field of the READ packet. These CALL_STATUS codes are for
SAR_READ_PACKET_CURRENT_VERSION = 3 and above. A list of all call status codes
is available as READ_CALL_STATUS_LIST, an 18-bit status data entity defined in the
element SAR$RPKTD.
Table 17–3. SAR$: READ Procedure CALL_STATUS Codes
Octal Code Status
0 Normal return from SAR$.
01 End-of-file condition reached by SAR_READ.
7833 1733–004 17–17

SAR$ READ
Table 17–3. SAR$: READ Procedure CALL_STATUS Codes
Octal Code Status
02 An I/O error has occurred in a READ procedure. See the IO_STATUS_CODE
field for the status code and Table 17–4.
03 An outdated READ packet version is being used.
04 An invalid READ packet version is being used.
05 An invalid value is specified for LINE_NUMBER_FORMAT.
06 The value for IMAGE_BUFFER_ADDRESS is NULL; an address must be
given for the input image buffer.
07 The IMAGE_BUFFER_WORD_LENGTH is zero; a length must be given for
the input image buffer.
010 An invalid value is specified for REQUEST_TYPE.
011 An invalid value is specified for UNTRANSLATE_MODE.
012 The value for INPUT_BUFFER_WORD_LENGTH is too small; use the word
length returned in RECOMMENDED_BUFFER_SIZE.
013 The input file or element accessed is not SDF.
014 An invalid value is specified in the ACCESS_TYPE field of the file information
packet.
015 An invalid address is specified in the READ_ADDRESS field; either the word
offset is greater than 27 or the sector address is greater than the highest
mass storage sector address of the file.
016 The input image is too long to fit in the image buffer. The image buffer word
length necessary to hold the entire image is returned in the field
RECOMMENDED_BUFFER_SIZE. To reread the image, call SAR_READ with
a larger IMAGE_BUFFER and IMAGE_BUFFER_WORD_LENGTH, and set the
READ_ADDRESS to IMAGE_ADDRESS returned on the previous call.
017 The character text is too long to fit in the text buffer and has been truncated.
The text buffer byte length necessary to hold the character text is returned in
the field RECOMMENDED_BUFFER_SIZE.
020 The number of attributes is too large to fit in the attribute table. The attribute
table word length necessary to hold all the attributes is returned in the field
RECOMMENDED_BUFFER_SIZE.
021 A partial image was read by SYMB$; call SAR_READ again to continue
reading the image.
022 An invalid SDF file or element label control record was read.
023 An invalid SDF control record was read.
024 The image read contains incorrectly formatted ACD or incorrectly formatted
embedded shift-coded kanji.
17–18 7833 1733–004

Table 17–3. SAR$: READ Procedure CALL_STATUS Codes
Octal Code Status
025 An invalid character set type was read.
SAR$ READ
026 The READ packet is not initialized; a call to SAR_OPEN_INPUT must be made
before calls to SAR_READ or SAR_CLOSE_INPUT.
027 An incorrect ACD subroutine version is being used with SAR$.
030 The file name buffer address in the FIP is NULL; an address of an SDF file
name must be specified.
031 The file name buffer address in the FIP is NULL; an address of a symbiont file
name must be specified.
032 An illegal value is specified for the file name buffer byte length; legal values
are from 1 to 12.
033 The input I/O buffer address is NULL; this buffer must be provided when
reading to an SDF file or element.
034 The SDF data record or control record read exceeds the maximum allowed
length of an SDF record.
0100 An unrecognized error has occurred in the SDFI routine. The SDFI error code
is returned in the SUB_STATUS field.
0101 An unrecognized error has occurred in an ACD subroutine. The ACD error
code is returned in the SUB_STATUS field.
0102 An unrecognized error has occurred in executing ER SYMB$. The SYMB$
error code is returned in the SUB_STATUS field.
0103 An incorrect SDFI packet version is being used. The correct SDFI packet
version is returned in the SUB_STATUS field.
0104 An incorrect ER SYMB$ packet version is being used. The correct SYMB$
packet version is returned in the SUB_STATUS field.
A CALL_STATUS code of 0100 or greater is a SAR$ internal error.
The READ procedure I/O status codes listed in Table 17–4 may be returned to the caller
in the IO_STATUS field of the READ packet.
Table 17–4. SAR$: READ Procedure IO_STATUS Status List
Octal Code Status
0 Normal I/O status.
01 to 40 See Table C–2, I/O Status Codes, ER Programming Reference Manual for
an explanation of the I/O status codes.
7833 1733–004 17–19

SAR$ READ
17.2. READ Function/MASM Interface
The SAR$ READ procedures can be called directly from MASM. The SAR$ data
structure definitions and procedure calls are defined by MASM procedures (PROCs).
The element SAR$PROCS contains these PROCs.
17.2.1. READ Packet and Data Area Description
The SAR$ READ function requires a READ packet and data area for the open-input, read,
and close-input calls. The S$ARRPDEF PROC generates the EQUFs defining the READ
packet fields. The word length of the MASM READ packet and data area is at label
SR$PKTWLEN defined by the S$ARRPDEF PROC (the current length is 72 words).
17.2.1.1. Required Information for READ Procedures
The calling program must set the following fields of the READ packet to appropriate
values:
SR$PKTVER
The READ packet data structure version. The current version is equal to the label
SR$CURVER defined by the S$ARRPDEF PROC. SR$PKTVER must not be modified
between calls to the SAR$ READ routine.
SR$FIPADDR
The address of the input file information packet. This packet is supplied by the caller
(see 16.1). Set this field to zero if input is from the runstream.
SR$INPBUF
The address of the input buffer, used to read images from the input file or element.
This field is defined only if input is from an SDF file or element. It is omitted if input
is from the runstream or an alternate READ$ file. Subsection 16.1.2 describes the
input buffer.
SR$INPBUFL
The length in words of the input buffer. It must be of length 28 * dpf * n, where dpf
is the disk prepping factor and n is a positive integer. This field is defined only if
input is from an SDF file or element. It is omitted if input is from the runstream or
an alternate READ$ file.
SR$IMGBUF
The address of the input image buffer into which SAR$ places individual images
from the input buffer. Subsection 16.1.2 describes the image buffer.
17–20 7833 1733–004

SR$IMGBUFL
The length in words of the input image buffer.
SR$TEXBUF
SAR$ READ
The address of the input text buffer into which SAR$ places the character text of the
image read. Subsection 16.1.2 describes the text buffer.
SR$TEXBUFL
The length in 9-bit bytes of the input text buffer.
SR$ATTRIB
The address of the input attribute table, into which SAR$ places the attributes
describing the character text of the image read. This field is undefined if the
attribute table word length is zero. Subsection 16.1.2 describes the format of the
attribute table.
SR$ATTRIBL
The length in words of the input attribute table. A length of zero indicates that there
is no input attribute table.
17.2.1.2. Optional Information for READ Procedures
The calling program may optionally set the following fields of the READ packet. The
default values are obtained by zero-filling the READ packet before placing any
information in the packet.
SR$SELLST
The address of the select list that specifies which attributes to return to the caller.
This field is undefined if the select list byte length is zero. Subsection 16.1.2
describes the format of the select list.
SR$SELLSTL
The length in 9-bit bytes of the select list. A length of zero indicates that there is no
select list (default).
7833 1733–004 17–21

SAR$ READ
SR$REQTYPE
The requested type of input.
0
1
SR$LNUMFMT
Do not search for embedded shift-coded kanji in ASCII/ISO (default).
Search for any embedded shift-coded kanji in ASCII/ISO input, and convert it into
internal format (text part and attributes part). Subsection 16.2 describes internal
format.
The format of line numbers returned by SAR$ to the caller.
0
1
2
3
Use the input line number type read with the input image; it may be either a CTS
or fractional line number (see 1 and 2 below). If no line number exists for the
input image, SAR$ increments the last line number by 1. If the input contains
mixed line number types (SR$LNUMTYP), the line number will be compared to
the previous line number, and if necessary, incremented. If the input does not
have any line numbers, SAR$ generates sequential line numbers with initial
value 1 and increment value 1 (default).
SAR$ generates sequential CTS line numbers with an initial value of 10 and
increment value of 10.
SAR$ generates sequential fractional line numbers with an initial value of 10 and
an increment value of 10.
No line numbers are returned to caller.
17–22 7833 1733–004

SR$UNTRFLG
The untranslate mode flag setting.
0
1
SR$SDFCNTL
SAR$ READ
Untranslate mode is off: an error is returned if SAR$ reads a character set type
other than 00 (Fieldata), 01 (ASCII/ISO), 077 (ACD) (default), or ASCII-like.
Untranslate mode is on: all input is passed to the caller untranslated.
This field specifies which SDF control records to return to the caller. Bits 0 to 31
may be set by the caller, where bit 0 is the leftmost bit of the field. If bit n is set, the
control record type (n + 040) is returned to the caller. The image control word of the
control record is returned in SR$SDFICW, and any data words of the control record
are returned in the text buffer. If this field is set to zero, no control records are
returned to the caller (default).
Note that the control record type 051 is not returned unless it is used to continue a
type 061 control record. Therefore, it is suggested that the caller specify that type
051 records be returned if type 061 records are desired, and vice-versa.
SR$ADDRSEC
The mass storage sector address of the next image to be read. This field is used if
the image to be read is not the next sequential image. If this field is set to zero, the
next sequential image is read (default). It is undefined if the input is not from an SDF
file or element. This field contains SR$ADDRWO in S1 of the word.
SR$ADDRWO
The word offset into the mass storage sector address of the next image to be read.
This field is used if the image to be read is not the next sequential image. If this
field is set to zero, the next sequential image is read (default). This field is undefined
if the input is not from an SDF file or element.
17.2.1.3. Information Returned by READ Procedures
The following fields of the READ packet contain values returned to the calling program
by the SAR$ READ procedures.
SR$STATUS
The READ function status word; it contains the call status in H2, the substatus in T1,
and the I/O status in S3.
7833 1733–004 17–23

SAR$ READ
SR$CALLST
The status code of the current open-input, read, or close-input function calls. See
Table 17–6 for an explanation of the octal status codes.
SR$IOSTAT
The status of any I/O operations performed by the READ procedures. See
Table 17–7 for the octal status codes.
SR$SYMBST
The status word returned from an ER SYMB$ request. See the SYMB$ section of
the Exec ER Programming Reference Manual for further details on the SYMB$
status word.
SR$RECBUFL
The recommended buffer or table length when an invalid length is specified or when
an overflow occurs.
SR$TEXTLEN
The length in 9-bit bytes of the character text returned in the text buffer.
SR$NUMATTR
The number of attributes returned in the attribute table.
SR$CHARTYP
The character set type of the image returned to the caller:
0 Fieldata 6-bit characters
01 ASCII/ISO 9-bit characters
077 Attributed character data (ACD)
A value of any ASCII-like character set type defined in Table H–1.
If SR$UNTRFLG is zero (untranslate mode off), then any Fieldata images read are
translated to ASCII/ISO before they are returned to the caller. See 17.3 for details on
allowed input character set types.
SR$INCHARTYP
The character set type of the image in the source input file or element. Contains the
code type from the last 050 or 042 control record encountered in the input file or
element.
17–24 7833 1733–004

SR$IMGSEC
SAR$ READ
The mass storage sector address of the SDF image read. This field is undefined if
input is from the runstream or an alternate READ$ file. SR$IMGWO is contained in
S1 of this field.
SR$IMGWO
The word offset into the mass storage sector address of the SDF image read. This
field is undefined if input is from the runstream or an alternate READ$ file.
SR$LNUMTYP
The type of line number returned with the image read:
0
1
2
SR$LNUMINT
No line number was read from the input; an SAR$ generated line number is
returned. See SR$LNUMFMT in 17.2.1.2.
A CTS line number is returned.
A fractional line number is returned.
The line number returned by SAR$. It may be a CTS line number, the integer part of
a fractional line number, or a generated sequential line number (see SR$LNUMTYP).
SR$LNUMF1
The first 10 digits of the fractional part of a fractional line number. This field is
defined only if SR$LNUMTYP is 2.
SR$LNUMF2
The second 10 digits of the fractional part of a fractional line number. This field is
defined only if SR$LNUMTYP is 2.
SR$LNUMF3
The third 10 digits of the fractional part of a fractional line number. This field is
defined only if SR$LNUMTYP is 2.
SR$LNUMF4
The fourth 10 digits of the fractional part of a fractional line number. This field is
defined only if SR$LNUMTYP is 2.
7833 1733–004 17–25

SAR$ READ
SR$SDFICW
The image control word for the SDF record read. This field is defined only if input is
from an SDF file or element. If bit 1 of SR$SDFICW is set, the image is a control
record. If bit 1 of SR$SDFICW is clear, the image is a data record. Bit 1 is the
leftmost bit of the field. See the Data Structures Programming Reference Manual
for further information on System Data Format (SDF) image control words.
SR$ICWTYPE
If the image is a control record, this field contains the control record type. If the
image is a data record, this field is undefined.
SR$ICWLEN
If the image is a control record, this field contains the length in words of the control
record. If the image is a data record, this field is undefined.
SR$ICWCHAR
This field contains the image character set type, if applicable for this control record
or data record.
17.2.1.4. READ Packet Definition PROC
The PROC S$ARRPDEF generates the EQUFs to define the READ packet. The calling
program may optionally attach an X-register and a B-register to these EQUFs. This
allows the calling program to allocate storage space for the READ packet either statically
at assembly time or dynamically at execution time. The calling program may display the
EQUF labels by setting the display-flag parameter on the PROC call. This PROC also
generates EQUs defining the READ packet current version and word length at labels
SR$CURVER and SR$PKTWLEN, respectively.
Calling Format
S$ARRPDEF x-reg,b-reg,dispflg
Parameters
x-reg
b-reg
The X-register to be attached to the READ packet EQUFs. If x-reg is omitted, no
X register is attached to the EQUFs.
The B-register to be attached to the READ packet EQUFs. If it is omitted, no
B register is attached to the EQUFs.
17–26 7833 1733–004

dispflg
A flag to display a table of the READ packet EQUFs. If it is set to ‘D’, the field
names are displayed; otherwise the field names are not displayed.
Example
$ASCII
$INCLUDE ‘MAXR$’
S$ARRPDEF X9,B2,’D’
SAR$ READ
The PROC call S$ARRPDEF of this example generates EQUFs using registers X9 and B2
and displays a description of each packet field.
17.2.2. Buffers and Tables for MASM READ Procedures
All buffers and tables must be provided by the calling program. The recommended
lengths for the buffers and tables are equated to labels in the S$ARRPDEF PROC.
These lengths and labels are listed in Table 17–5. These definitions simplify the creation
of required buffers and tables for the calling program.
Table 17–5. SAR$: MASM READ Buffer and Table Lengths
Label Value
SR$INPBUFDL (Input buffer word length) 448
SR$IMGBUFDL (Image buffer word length) 63
SR$TEXBUFDL (Text buffer byte length) 132
SR$ATTRIBDL (Attribute table word length) 40
SR$SELLSTDL (Select list byte length) 4
17.2.3. READ Procedures Called from MASM
The MASM procedures for the READ function are
• S$AROPENI (open input)
• S$ARREAD (read)
• S$ARCLOSI (close input)
The calling sequences for these procedures are generated by MASM PROCs, contained
in the SYSLIB file (SYS$LIB$*SYSLIB) or SYS$*RLIB$.
7833 1733–004 17–27

SAR$ READ
17.2.3.1. Open-Input Procedure Call (S$AROPENI)
The READ packet and data area must be initialized before any images are read. The
S$AROPENI PROC performs the READ packet initialization.
Initial Conditions
The calling program sets the following parameters in the READ packet to appropriate
values before calling S$AROPENI:
• Required parameters (described in 17.2.1.1)
SR$PKTVER
SR$INPBUFL
SR$FIPADDR
SR$IMGBUF
SR$INPBUF
SR$IMGBUFL
• Optional parameters (described in 17.2.1.2)
SR$SELLST
SR$UNTRFLG
SR$SELLSTL
SR$LNUMFMT
SR$REQTYPE
SR$SDFCNTL
Calling Format
S$AROPENI rpkt
error return
normal return
where rpkt is a label identifying the starting address of the READ packet and data area.
Note: It is recommended that the calling program zero-fill the READ packet before
placing any parameters in the packet.
Returns
If the error return from S$AROPENI is taken, A1 contains the call status code, A2
contains the I/O status code, and A3 contains the substatus code. These status codes
are also returned in the packet fields SR$CALLST, SR$IOSTAT, and T1 of SR$STATUS,
respectively. See 17.2.4 for an explanation of the status codes.
If the normal return from S$AROPENI is taken, the initialization of the READ packet is
successful.
17–28 7833 1733–004

17.2.3.2. Read Procedure Call (S$ARREAD)
SAR$ READ
The S$ARREAD PROC returns one image from the symbolic input to the calling program,
placing the character text in the text buffer and the attributes in the attribute table.
Initial Conditions
The calling program sets the following parameters in the READ packet to appropriate
values before calling S$ARREAD:
• Required parameters (described in 17.2.1.1)
SR$TEXBUF
SR$ATTRIBL
SR$TEXBUFL
SR$ATTRIB
• Optional parameters (described in 17.2.1.2)
SR$ADDRSEC
SR$SELLSTL
SR$ADDRWO
SR$SELLST
Calling Format
S$ARREAD rpkt
error return
end-of-file return
normal return
where rpkt is a label identifying the starting address of the READ packet and data area.
Returns
Each call to S$ARREAD reads one image from the input. If the normal return is taken,
S$ARREAD returns the character text in the text buffer, the attributes in the attribute
table, and other information in the READ packet. S$ARREAD does not space-fill the text
buffer if the text length is shorter than the text buffer length. If the text length is longer
than the text buffer, S$ARREAD truncates the text to the length of the text buffer and
takes the error return. See 17.2.1.3 for a list of the fields that contain information
returned by S$ARREAD to the calling program.
If the error return from S$ARREAD is taken, A1 contains the call status code, A2
contains the I/O status code, and A3 contains the substatus code. These status codes
are also returned in the packet fields SR$CALLST, SR$IOSTAT, and T1 of SR$STATUS,
respectively. See 17.2.4 for an explanation of the status codes.
If the end-of-file return from S$ARREAD is taken, the last read request encountered an
end-of-file condition. A1 contains the call status code, A2 contains the I/O status code,
and A3 contains the substatus code. These status codes are also returned in the packet
fields SR$CALLST, SR$IOSTAT, and T1 of SR$STATUS, respectively.
7833 1733–004 17–29

SAR$ READ
17.2.3.3. Close-Input Procedure Call (S$ARCLOSI)
The S$ARCLOSI PROC closes the input operation.
Calling Format
S$ARCLOSI rpkt
error return
normal return
where rpkt is a label identifying the starting address of the READ packet and data area.
Returns
If the error return from S$ARCLOSI is taken, A1 contains the call status code, A2
contains the I/O status code, and A3 contains the substatus code. These status codes
are also returned in the packet fields SR$CALLST, SR$IOSTAT, and T1 of SR$STATUS,
respectively. See 17.2.4 for an explanation of the status codes.
If the normal return from S$ARCLOSI is taken, the input is successfully closed.
17.2.4. Status Lists for MASM READ Procedures
The READ procedure call status codes listed in Table 17–6 may be returned to the calling
program in the SR$CALLST field of the READ packet. These call status codes are for
SR$CURVER = 3 and above.
Table 17–6. SAR$: READ Procedure SR$CALLST Status Codes
Octal Code Status
0 Normal return from SAR$.
01 End-of-file condition reached by S$ARREAD.
02 An I/O error has occurred in a READ procedure. See the SR$IOSTAT field for
the status code and Table 17–7.
03 An outdated READ packet version is being used.
04 An invalid READ packet version is being used.
05 An invalid value is specified for SR$LNUMFMT.
06 The value for SR$IMGBUF is zero; an address must be given for the input
image address.
07 The value for SR$IMGBUFL is zero; a length must be given for the input image
address.
010 An invalid value is specified for SR$REQTYPE.
011 An invalid value is specified for SR$UNTRFLG.
17–30 7833 1733–004

Table 17–6. SAR$: READ Procedure SR$CALLST Status Codes
Octal Code Status
012 The value for SR$INPBUFL is too small; use the word length returned in
SR$RECBUFL.
013 The input file or element accessed is not SDF.
014 An invalid value is specified in the FIP$ACTYP field of the file information
packet.
SAR$ READ
015 An invalid address is specified in SR$ADDRSEC; either the word offset is
greater than 27 or the sector address is greater than the highest mass storage
sector address of the file.
016 The input image is too long to fit in the image buffer. The image buffer word
length necessary to hold the entire image is returned in the field
SR$RECBUFL. To reread the image, call SAR$ READ with a larger image
buffer and image buffer word length (SR$IMGBUFL) and set the read address
(SR$ADDRSEC and SR$ADDRWO) to the image address (SR$IMGSEC and
SR$IMGWO) returned on the previous call.
017 The character text is too long to fit in the text buffer and has been truncated.
The text buffer byte length necessary to hold the character text is returned in
the field SR$RECBUFL.
020 The number of attributes is too large to fit in the attribute table. The attribute
table word length necessary to hold all the attributes is returned in the field
SR$RECBUFL.
021 A partial image was read by SYMB$; call S$ARREAD again to continue reading
the image.
022 An invalid SDF file or element label control record was read.
023 An invalid SDF control read was read.
024 The image read contains incorrectly formatted ACD or incorrectly formatted
embedded shift-coded kanji.
025 An invalid character set type was read.
026 The READ packet is not initialized; a call to S$AROPENI must be made before
calls to S$ARREAD or S$ARCLOSI.
027 An incorrect ACD subroutine version is being used with SAR$.
030 The file name buffer address in the FIP is zero; an address of an SDF file name
must be specified.
031 The file name buffer address in the FIP is zero; an address of a symbiont file
name must be specified.
032 An illegal value is specified for the file name buffer byte length; legal values are
from 1 to 12.
033 The input I/O buffer address is zero; this buffer must be provided when
reading from an SDF file or element.
7833 1733–004 17–31

SAR$ READ
Table 17–6. SAR$: READ Procedure SR$CALLST Status Codes
Octal Code Status
034 The SDF data record or control record read exceeds the maximum allowed
length of an SDF record.
0100 An unrecognized error has occurred in the SDFI routine. The SDFI error code
is returned in T1 of the SR$STATUS field.
0101 An unrecognized error has occurred in an ACD subroutine. The ACD error
code is returned in T1 of the SR$STATUS field.
0102 An unrecognized error has occurred in executing ER SYMB$. The SYMB$
error code is returned in T1 of the SR$STATUS field.
0103 An incorrect SDFI packet version is being used. The correct SDFI packet
version is returned in T1 of the SR$STATUS field.
0104 An incorrect ER SYMB$ packet version is being used. The correct SYMB$
packet version is returned in T1 of the SR$STATUS field.
A SR$CALLST status code of 0100 or greater is a SAR$ internal error.
The READ procedure I/O status codes listed in Table 17–7 may be returned to the caller
in the SR$IOSTAT field of the READ packet.
Table 17–7. SAR$: READ Procedure SR$IOSTAT Status Codes
Status code Explanation
0 Normal I/O status
01 to 40 See Table C–2, I/O Status Codes, Exec ER Programming Reference Manual.
17–32 7833 1733–004

SAR$ READ
17.3. Supported Character Set Types for the READ
Function
Table H–1 lists 64 character set types defined for the OS 2200 system. Forty of these
are referred to as ASCII-like. This means that the character set is essentially identical to
the ASCII/ISO character set in the octal range 000 through 01777, with any differences
being minor. Table H–1 identifies the character set types that are ASCII-like.
Throughout this section, wherever ASCII or ASCII/ISO is used, the SAR$ capabilities
apply equally to all ASCII-like character sets.
The following character set types may be read from input files:
• Fieldata 6-bit characters
• ASCII-like characters, including ASCII/ISO 9-bit characters and ASCII/ISO 9-bit
characters with embedded shift-coded kanji
• Attributed character data (ACD)
17.3.1. Fieldata
If the input images are in the Fieldata character set, they are translated to the ASCII/ISO
character set before they are returned to the caller. The translated images are returned
to the caller in the text buffer. No attributes are returned to the caller.
17.3.2. ASCII/ISO and ASCII-like
If the input images are in the ASCII/ISO character set, they are returned to the caller in
the text buffer. No attributes are returned to the caller.
7833 1733–004 17–33

SAR$ READ
17.3.3. ASCII/ISO with Embedded Shift-Coded Kanji
If the input images contain embedded shift-code bytes and REQUEST_TYPE is
S'Translate_embedded_KANJI' (for PLUS) or SR$REQTYPE is 1 (for MASM), the READ
procedures remove the embedded shift-code bytes and return the images in internal
format. The character text is returned in the text buffer, and the attributes are returned
in the attribute table. Subsection 16.2 describes internal format.
If REQUEST_TYPE is S'Pass_embedded_KANJI' (for PLUS) or SR$REQTYPE is 0
(for MASM), the READ procedures do not remove the embedded shift-code bytes.
The entire image is returned untranslated in the text buffer.
Multiple Block Sequence Indicator
If the input images are from a card reader file created by the Nippon-go Preprocessors
for ASCII COBOL (NCOB) and ASCII FORTRAN (NFTN), they may contain a logical record
that is divided into two or more physical records. The record is divided because these
processors run on EXEC level 38R5 or lower levels that do not allow more than 132
characters in a record. To read one logical record rather than two or more physical
records, the multiple block sequence indicator is set in the last shift code of a record.
The records must reside in a symbiont file, and the text buffer must be at least 264
characters long.
17.3.4. Attributed Character Data
If the input images are attributed character data (ACD), the READ procedures translate
the images into internal format. The text part is returned in the text buffer, and the
attributes are returned in the attribute table. Subsection 16.2 describes internal format.
The Data Structures Programming Reference Manual describes ACD format.
17–34 7833 1733–004

Section 18
SAR$ WRITE
18.1. WRITE Function/PLUS Interface
The SAR$ WRITE function writes symbolic images to SDF files, SDF elements, and
symbiont files (PRINT$, PUNCH$, alternate PRINT$, and alternate PUNCH$). If an SDF
element is written to, the element is added to the program file table of contents when
the WRITE operation is completed (by calling SAR_CLOSE_OUTPUT).
The SAR$ WRITE function procedures can be called from PLUS. These procedures are
• SAR_OPEN_OUTPUT
• SAR_WRITE
• SAR_WRITE_CONTROL
• SAR_CLOSE_OUTPUT
All SAR$ data structure definitions and procedure calls are contained in definition
elements. These elements are obtained with the PLUS COPY statement.
Empty symbiont output files may not be created by simply calling SAR_OPEN_OUTPUT
followed by SAR_CLOSE_OUTPUT. An empty symbiont file may be created by setting
IMAGE_CONTROL_WIDTH to a nonzero value when calling SAR_OPEN_OUTPUT,
followed by a call to SAR_CLOSE_OUTPUT. This will cause a print control image to be
generated, which will open the output file. If IMAGE_CONTROL_WIDTH is zero when
creating an "empty" symbiont file, an error will occur during SAR_CLOSE_OUTPUT.
18.1.1. WRITE Packet Data Structure Description
The SAR$ WRITE function requires a WRITE packet data structure for the
SAR_OPEN_OUTPUT, SAR_WRITE, SAR_WRITE_CONTROL, and
SAR_CLOSE_OUTPUT procedure calls.
The type definition for this data structure is contained in the element SAR$WPKTD in the
SYSLIB file (SYS$LIB$*SYSLIB) or SYS$*RLIB$. It is obtained with the COPY
statement. The identifier for the WRITE packet data structure type is
SAR_WRITE_PACKET.
7833 1733–004 18–1

SAR$ WRITE
The calling program must provide storage space for the WRITE packet data structure
plus any necessary buffers and tables since SAR$ does not have any D-bank storage.
The length of the WRITE packet is equal to the constant
SAR_WRITE_PACKET_WORD_LENGTH defined in the element SAR$WPKTD (current
length is 36 words). SAR_WRITE_PACKET is defined as LOCATABLE.
The calling program places information in the WRITE packet data structure and passes
the address of the WRITE packet data structure to SAR$ as a parameter on the
procedure calls.
18.1.1.1. Required Information for WRITE Procedures
The calling program must set the following fields of the WRITE packet to an appropriate
value:
PACKET_VERSION
PLUS Attribute: 6-bit integer
The WRITE packet data structure version. The current version is equal to the
constant SAR_WRITE_PACKET_CURRENT_VERSION defined in the element
SAR$WPKTD.
OUTPUT_FILE_INFO_PKT_ADDRESS
PLUS Attribute: word pointer
The address of the output file information packet. This packet is supplied by the
caller (see 18.1.2). Set to NULL if OUTPUT_FILE_TYPE is S'PRINT_File',
S'PUNCH_File', or S'No_Output'.
OUTPUT_BUFFER_ADDRESS
PLUS Attribute: word pointer
The address of the output buffer, used to write images to the output file or element.
This field is defined only if output is to an SDF file or element. It is omitted if output
is to a symbiont file. Subsection 18.1.2 describes the output buffer.
OUTPUT_BUFFER_WORD_LENGTH
PLUS Attribute: 18-bit integer
The length in words of the output buffer. It must be of length 28 * dpf * n, where
dpf is the disk prepping factor and n is a positive integer. This field is defined only if
output is to an SDF file or element. It is omitted if output is to a symbiont file.
18–2 7833 1733–004

IMAGE_BUFFER_ADDRESS
PLUS Attribute: word pointer
SAR$ WRITE
The address of the output image buffer, into which SAR$ places the images to be
written out. Subsection 18.1.2 describes the image buffer.
IMAGE_BUFFER_WORD_LENGTH
PLUS Attribute: 18-bit integer
The length in words of the output image buffer.
TEXT_BUFFER_ADDRESS
PLUS Attribute: word pointer
The address of the output text buffer, into which the caller places the character text
to be written out. Subsection 18.1.2 describes the text buffer.
TEXT_BUFFER_BYTE_LENGTH
PLUS Attribute: 18-bit integer
The length in 9-bit bytes of the character text in the text buffer.
ATTRIBUTE_TABLE_ADDRESS
PLUS Attribute: word pointer
The address of the output attribute table, into which the caller places the attributes
describing the character text to be output. This field is undefined if the
ATTRIBUTE_TABLE_WORD_LENGTH is zero. Subsection 18.1.2 describes the
format of the attribute table.
ATTRIBUTE_TABLE_WORD_LENGTH
PLUS Attribute: 18-bit integer
The number of valid entries in the attribute table. (Each entry is one word.) A value
of zero indicates there is no output attribute table.
SDF_IMAGE_CONTROL_WORD
PLUS Attribute: word logical
If OUTPUT_RECORD_TYPE is S'Control_record', the caller must place the SDF
image control word in this field and place any data words of the control record in the
output text buffer. Otherwise, this field is omitted.
7833 1733–004 18–3

SAR$ WRITE
18.1.1.2. Optional Information for WRITE Procedures
The calling program may optionally set the following fields of the WRITE packet.
The default values are obtained by zero-filling the WRITE packet before placing any
information in the packet.
OUTPUT_FILE_TYPE
PLUS Attribute: 6-bit status
The file type that output images are written to:
S'SDF_element'
Write to an SDF element (default).
S'SDF_file'
Write to an SDF file.
S'PRINT_file'
Write to the standard PRINT$ file.
S'PUNCH_file'
Write to the standard PUNCH$ file.
S'Alternate_PRINT_file'
Write to an alternate PRINT$ file.
S'Alternate_PUNCH_file'
Write to an alternate PUNCH$ file.
S'No_output'
Construct the output image in the image buffer, but do not write it out.
The output file may not be a tape file.
18–4 7833 1733–004

OUTPUT_RECORD_TYPE
PLUS Attribute: 6-bit status
The type of record to be written;
S'Data_record'
SDF data record for SDF files or elements (default).
S'Control_record'
SDF control record for SDF files or elements.
S'Symbiont_record'
Data record for symbiont files.
S'Write_control_record'
Write control record for symbiont files.
OUTPUT_LINE_NUMBER_TYPE
PLUS Attribute: 6-bit status
The type of line numbers used for the output images:
S'No_line_numbers'
No line numbers are written out (default).
S'Generate_fractional'
SAR$ WRITE
Generate sequential fractional line numbers with initial value 10 and increment
value 10.
S'Generate_CTS'
Generate sequential CTS line numbers with initial value 10 and increment value
10.
S'Fractional_in_packet'
Output the fractional line numbers supplied by the caller in the packet.
S'CTS_in_packet'
Output the CTS line numbers supplied by the caller in the packet.
7833 1733–004 18–5

SAR$ WRITE
OUTPUT_IMAGE_CHARACTER_TYPE
PLUS Attribute: 6-bit status
The character set type to be output by SAR$:
S'ASCII_ISO'
S'ACD'
ASCII/ISO 9-bit characters (default) and all other ASCII-like types in Table H–1.
Attributed character data (ACD).
A value of any ASCII-like character set type in Table H–1.
Other character set types may not be written out by SAR$. See 18.3 for details on
the allowed output character set types.
INPUT_TEXT_CHARACTER_TYPE
PLUS Attribute: 6-bit status
If the character set type of the text placed in the text buffer is Fieldata, this field
must be set to S'Fieldata'. Otherwise, this field is set to S'ASCII_ISO' (default). The
WRITE procedure converts Fieldata to ASCII/ISO before it is written out.
UNTRANSLATE_MODE
PLUS Attribute: 6-bit status
The untranslate mode flag setting:
S'Off'
S'On'
An error is returned if character set types other than ASCII/ISO, ACD, or ASCIIlike
are specified for output (default).
Character set types other than ASCII/ISO, ACD, or ASCII-like are written to the
output file untranslated. This is set to output Fieldata.
18–6 7833 1733–004

GENERAL_SDF_LABEL_FLAG
PLUS Attribute: 6-bit status
SAR$ WRITE
A flag controlling the generation of the SDF file or element label control record:
S'On'
S'Off'
If output is to an SDF file or element, write out a label control record with
general file type 'S' (default).
Do not write out an SDF label control record. If output is to an SDF file or
element, the caller must write this record.
CLOSING_BREAKPOINT_FLAG
PLUS Attribute: 6-bit status
A flag controlling symbiont file closing breakpoints:
S'On'
S'Off'
If output is to alternate symbiont file filename, execute an '@BRKPT filename'
command when SAR_CLOSE_OUTPUT is called (default).
Do not execute an '@BRKPT filename' command.
OUTPUT_IMAGE_LINE_SPACING
PLUS Attribute: 18-bit integer
For symbiont file output, the number of lines to space before printing the image
(default is 1).
ELEMENT_CREATION_DATE_AND_TIME
PLUS Attribute: word logical
For SDF element output, the creation date and time of the element to be entered in
the program file table of contents. The date and time format is described under
"Program File Format," in the Data Structures Programming Reference Manual. The
default is the current date and time when SAR_CLOSE_OUTPUT is called.
7833 1733–004 18–7

SAR$ WRITE
LINE_NUMBER_INTEGER_PART
PLUS Attribute: word integer
The line number to be written out with the output image. It may be a CTS line
number or the integer part of a fractional line number (see
OUTPUT_LINE_NUMBER_TYPE). This field is used only for output types of SDF
files or SDF elements.
LINE_NUMBER_FRACTIONAL_PART (1:4)
PLUS Attribute: word integer
The fractional part of a fractional line number to be written out with the output
image. Each word contains 10 digits of the fraction. This field is used only for
output types of SDF files or SDF elements.
TRIM_BLANKS_FLAG
PLUS Attribute: 6-bit status
A flag that determines if words of blank (space) characters are trimmed from the end
of ASCII output images before they are written out:
S'Off'
S'On'
Do not trim blank characters (default).
Trim blank characters from output image.
IMAGE_CONTROL_WIDTH
PLUS Attribute: 18-bit integer
The initial print or punch control width of the output file. The default is 33 words
(132 ASCII characters). This field is used only for symbiont output file types. This is
only recognized during the SAR_OPEN_OUTPUT call. If it is modified in subsequent
calls to SAR_WRITE, it will be ignored. If the output file type is a symbiont file,
SAR$ may expand the line width if necessary. The line width will be reset to the
print or punch device default in SAR_CLOSE_OUTPUT. This is to allow for the
additional bytes required in the ASCII/ISO with embedded shift-coded kanji and ACD
character types and for transmitting large data records such as a full screen of
characters.
The constant SAR_PCW_CHARS_PER_WORD may be used to calculate the desired
IMAGE_CONTROL_WIDTH.
18–8 7833 1733–004

18.1.1.3. Information Returned by WRITE Procedures
SAR$ WRITE
The following fields of the WRITE packet contain values returned by the SAR$ WRITE
procedures to the calling program:
CALL_STATUS
PLUS Attribute: 18-bit status
The status of the current call to SAR_OPEN_OUTPUT, SAR_WRITE,
SAR_WRITE_CONTROL, or SAR_CLOSE_OUTPUT. See Table 18–3 for an
explanation of the WRITE procedure status codes. This field may be referenced as
an 18-bit logical field with the label CALL_STATUS_CODE.
SUB_STATUS_CODE
PLUS Attribute: 12-bit logical
This field contains additional information for particular CALL_STATUS codes.
IO_STATUS
PLUS Attribute: 6-bit status
The status of any I/O operations performed by SAR$. See Table 18–4 for the I/O
status codes. This field may be referenced as a 6-bit logical field with the label
IO_STATUS_CODE.
WRITE_STATUS_WORD
PLUS Attribute: word logical
A one-word combination of CALL_STATUS, SUB_STATUS, and IO_STATUS
contained in H2, T1, and S3, respectively.
SYMB_STATUS_WORD
PLUS Attribute: word logical
The status word returned from an ER SYMB$ request. See SYMB$ section, OS
2200 Exec ER Programming Reference Manual for further details on the ER SYMB$
status word.
RECOMMENDED_BUFFER_LENGTH
PLUS Attribute: 18-bit integer
The recommended buffer or table length when an invalid length is specified or when
an overflow occurs.
7833 1733–004 18–9

SAR$ WRITE
IMAGE_BYTE_LENGTH
PLUS Attribute: 18-integer
The length in bytes of the image written out by the SAR_WRITE procedure. For
images written to SDF files or elements, the length does not include the image
control word or the length of the line number records. For images written to
symbiont files, the length is the number of bytes transferred by the SYMB$ request.
IMAGE_ADDRESS_SECTOR
PLUS Attribute: 24-bit integer
The mass storage sector address to which the SDF image was written. This field is
undefined if output file type is not an SDF file or element. If a line number control
record (type 053) is written with the data record, this address is the sector address
of the line number control record corresponding to the data record.
IMAGE_ADDRESS_WORD_OFFSET
PLUS Attribute: 6-bit integer
The word offset into the mass storage sector address that the SDF image was
written to. This field is undefined if output file type is not an SDF file or element.
IMAGE_ADDRESS
PLUS Attribute: word machine integer
A one word combination of IMAGE_ADDRESS_SECTOR and
IMAGE_ADDRESS_WORD_OFFSET, contained in bits 13 to 36 and in bits 1 to 6,
respectively. (Bit 1 is the leftmost bit of the word.)
18.1.2. Buffers and Tables for PLUS WRITE Procedures
The SAR$ WRITE function requires that the following buffers and table be supplied by
the calling program:
• Output buffer
The output buffer is used to write to mass storage files. The calling program never
needs to access the output buffer, but it must provide it to SAR$. If the calling
program is using both the READ and WRITE functions of SAR$, then it cannot use
the same I/O buffer for both functions. The calling program must provide a separate
input and output buffer for each function.
18–10 7833 1733–004

SAR$ WRITE
• Image buffer
The image buffer is used to construct individual images from information in the text
buffer and attribute table and move them into the output buffer. Because images
can be written in different formats, this buffer is necessary to relieve the calling
program from having to build these formats. The calling program never needs to
access the image buffer, but it must provide it to SAR$. The calling program using
the READ and WRITE functions of SAR$ can use the same image buffer for both
functions.
• Text buffer
The text buffer is used to pass the characters of the output image to SAR$. The
calling program must place the characters sequentially in the text buffer, regardless
of the eventual output format or attributes that may apply to the characters. The
text buffer is one part of internal format (see 16.2). The calling program using the
READ and WRITE functions of SAR$ can use the same text buffer for both
functions.
• Attribute table
The attribute table is used to pass to SAR$ the attributes that apply to the characters
in the text buffer. Each attribute has a one-word entry in the attribute table which
follows the format in Figure 18–1.
index type value
0 17 18 26 27 35
Figure 18–1. SAR$: Attribute Table Entry
The calling program places the attribute entries into the attribute table. The attribute
table is the other part of internal format (see 16.2). If the output images will not
contain any attributes or if UNTRANSLATE_MODE is set to S (on), the attribute table
may be omitted by setting ATTRIBUTE_TABLE_ADDRESS to null (zero). The calling
program using the READ and WRITE functions of SAR$ can use the same attribute
table for both functions.
All buffers and tables must be provided by the calling program. The type definitions for
the buffers and tables and definitions for the default buffer and table lengths are
contained in the element SAR$DEFN in the SYSLIB file (SYS$LIB$*SYSLIB) or
SYS$*RLIB$. They may be obtained with the COPY statement. These definitions
simplify the creation of required buffers and tables for the calling program.
7833 1733–004 18–11

SAR$ WRITE
The default buffer and table lengths are listed in Table 18–1.
Table 18–1. SAR$: PLUS WRITE Buffer and Table
Length Defaults
Identifier Value
SAR_IO_BUFFER_WORD_LENGTH 448
SAR_IMAGE_BUFFER_WORD_LENGTH 63
SAR_TEXT_BUFFER_BYTE_LENGTH 132
SAR_ATTRIBUTE_TABLE_WORD_LENGTH 40
The buffer and table type definitions are listed in Table 18–2.
Table 18–2. SAR$: PLUS WRITE Buffer and Table
Type Definitions
Identifier Type
SAR_IO_BUFFER 448 words logical locatable
SAR_IMAGE_BUFFER 63 words logical locatable
SAR_TEXT_BUFFER 132 ASCII characters locatable
SAR_ATTRIBUTE_TABLE 40 words logical locatable
SAR_SELECT_LIST 4 bytes logical locatable
The element SAR$DEFN also contains other definitions necessary to SAR$.
18.1.3. WRITE Procedures Called from PLUS
The procedures for the WRITE function are
• SAR_OPEN_OUTPUT
• SAR_WRITE
• SAR_WRITE_CONTROL
• SAR_CLOSE_OUTPUT
The procedure declarations for SAR_OPEN_OUTPUT, SAR_WRITE,
SAR_WRITE_CONTROL, and SAR_CLOSE_OUTPUT are contained in the element
SAR$WRITE$DG in the SYSLIB file (SYS$LIB$*SYSLIB) or SYS$*RLIB$. This element is
obtained with the COPY statement. SAR$WRITE$DG contains all four procedure
declarations. All of the WRITE procedure modules are compiled with the G option using
the IBJ$ calling sequence.
18–12 7833 1733–004

18.1.3.1. SAR_OPEN_OUTPUT Procedure Call
SAR$ WRITE
The WRITE packet data structure must be initialized before any images are written out.
The SAR_OPEN_OUTPUT procedure performs the WRITE packet initialization.
Initial Conditions
The calling program sets the following parameters in the WRITE packet to appropriate
values before calling SAR_OPEN_OUTPUT:
• Required parameters (described in 18.1.1.1)
PACKET_VERSION
OUTPUT_FILE_INFO_PACKET_ADDRESS
OUTPUT_BUFFER_ADDRESS
OUTPUT_BUFFER_WORD_LENGTH
IMAGE_BUFFER_ADDRESS
IMAGE_BUFFER_WORD_LENGTH
• Optional parameters (described in 18.1.1.2)
OUTPUT_FILE_TYPE
OUTPUT_LINE_NUMBER_TYPE
OUTPUT_IMAGE_CHARACTER_TYPE
UNTRANSLATE_MODE
GENERAL_SDF_LABEL_FLAG
CLOSING_BREAKPOINT_FLAG
TRIM_BLANKS_FLAG
IMAGE_CONTROL_WIDTH
Note: The calling program must zero-fill the WRITE packet before placing any
parameters in the packet.
Calling Format
PROCEDURE SAR_OPEN_OUTPUT
(WRITE_PACKET_ADDRESS: WORD MACHINE POINTER)
IMPORTED ('SAR$OPENO$PG');
Returns
SAR_OPEN_OUTPUT returns the initialization status in the WRITE packet field
CALL_STATUS. If the status is S'Normal', the initialization of the WRITE packet is
successful. Otherwise, an error has occurred and CALL_STATUS contains the status
code. See 18.1.4 for a list of WRITE function status codes.
7833 1733–004 18–13

SAR$ WRITE
18.1.3.2. SAR_WRITE Procedure Call
The SAR_WRITE procedure writes images to the output file or element. Each call to
SAR_WRITE writes out one image. The calling program must supply the character text
of the image in the text buffer and the attributes for the text (if any) in the attribute table.
SAR_WRITE combines the text and attributes into the proper format and writes out the
image.
Initial Conditions
The calling program sets the following parameters in the WRITE packet to appropriate
values before calling SAR_WRITE:
• Required parameters (described in 18.1.1.1)
TEXT_BUFFER_ADDRESS
TEXT_BUFFER_BYTE_LENGTH
ATTRIBUTE_TABLE_ADDRESS
ATTRIBUTE_TABLE_WORD_LENGTH
• Optional parameters (described in 18.1.1.2)
OUTPUT_RECORD_TYPE
INPUT_TEXT_CHARACTER_TYPE
OUTPUT_IMAGE_LINE_SPACING
LINE_NUMBER_INTEGER_PART
LINE_NUMBER_FRACTIONAL_PART(1:4)
Calling Format
PROCEDURE SAR_WRITE
(WRITE_PACKET_ADDRESS: WORD MACHINE POINTER)
IMPORTED ('SAR$WRITE$PG');
Returns
SAR_WRITE returns the calling status in the WRITE packet field CALL_STATUS. If the
status is S'Normal', then the write was successful. The following fields of the WRITE
packet contain information returned by SAR$ to the calling program:
IMAGE_BYTE_LENGTH
IMAGE_ADDRESS_SECTOR
IMAGE_ADDRESS_WORD_OFFSET
These parameters are described in 18.1.1.3.
If the status returned from SAR_WRITE is not S'Normal', then an error has occurred and
CALL_STATUS contains the status code. See 18.1.4 for a list of WRITE function status
codes.
18–14 7833 1733–004

18.1.3.3. SAR_WRITE_CONTROL Procedure Call
SAR$ WRITE
The SAR_WRITE_CONTROL procedure performs the following write control functions
for symbiont files:
• Moves to the top of the next page
• Moves to logical line n
• Inserts a heading at the top of all succeeding pages
• Clears the heading from the top of all succeeding pages
• Sets the page length, top margin, bottom margin, and lines per inch
Initial Conditions
The calling program sets the following parameters in the WRITE packet to appropriate
values before calling SAR_WRITE_CONTROL:
• Required parameter (described below)
CONTROL_FUNCTION
• Optional parameters (described below)
LINE_NUMBER_ON_PAGE
PAGE_LENGTH
TOP_MARGIN_LENGTH
BOTTOM_MARGIN_LENGTH
LINES_PER_INCH
Calling Format
PROCEDURE SAR_WRITE_CONTROL
(WRITE_PACKET_ADDRESS: WORD MACHINE POINTER)
IMPORTED ('SAR$WCNTL$PG');
Parameters
CONTROL_FUNCTION
PLUS Attribute: 18-bit status
The WRITE control function to be performed by SAR_WRITE_CONTROL:
S'Top_of_page'
Move to the top of the next page (page eject).
S'Line_spacing'
Space to line n on the page, where n is the value set by the calling program in
the field LINE_NUMBER_ON_PAGE. If the current line location is equal to or
beyond n, space to line n of the next page.
7833 1733–004 18–15

SAR$ WRITE
S'Print_heading'
Insert a heading at the top of all succeeding pages. The heading text must be in
the ASCII/ISO character set with a maximum length of 96 characters. The caller
places the heading text in the text buffer, and the length of the heading text in
the field TEXT_BUFFER_BYTE_LENGTH.
S'Clear_heading'
Clear the heading from the top of all succeeding pages.
S'Set_margins'
Change the values for the page length, top margin, bottom margin, and lines per
inch. The values are set by the caller in fields PAGE_LENGTH,
TOP_MARGIN_LENGTH, BOTTOM_MARGIN_LENGTH, and LINES_PER_INCH.
A value of -1 for any of these fields results in the device standard value being
used.
LINE_NUMBER_ON_PAGE
PLUS Attribute: 18-bit integer
The logical line number on the page to space to. This field is defined only for the
CONTROL_FUNCTION S'Line_spacing'.
PAGE_LENGTH
PLUS Attribute: 18-bit signed integer
The number of lines in a page. This field is defined only for the
CONTROL_FUNCTION S'Set_margins'.
TOP_MARGIN_LENGTH
PLUS Attribute: 18-bit signed integer
The number of blank lines used for a top margin; it must be less than 63 lines.
This field is defined only for the CONTROL_FUNCTION S'Set_margins'.
BOTTOM_MARGIN_LENGTH
PLUS Attribute: 18-bit signed integer
The number of blank lines used for a bottom margin; it must be less than 63 lines.
This field is defined only for the CONTROL_FUNCTION S'Set_margins'.
18–16 7833 1733–004

LINES_PER_INCH
PLUS Attribute: 18-bit signed integer
SAR$ WRITE
The number of lines per inch; it may be 6, 8, or -1 (device standard value). This field
is defined only for the CONTROL_FUNCTION S'Set_margins'.
Returns
SAR_WRITE_CONTROL returns the calling status in the WRITE packet field
CALL_STATUS. If the status is S'Normal', then the write control operation was
successful.
If the status returned from SAR_WRITE_CONTROL is not S'Normal', then an error has
occurred and CALL_STATUS contains the status code. See 18.1.4 for a list of WRITE
function status codes.
18.1.3.4. SAR_CLOSE_OUTPUT Procedure Call
The SAR_CLOSE_OUTPUT procedure performs the necessary tasks to close the output
operation. If the output type is an SDF element, the element is added to the program
file table of contents.
Initial Condition
The calling program may set the following optional parameter in the WRITE packet to an
appropriate value before calling SAR_CLOSE_OUTPUT:
ELEMENT_CREATION_DATE_AND_TIME
This parameter is described in 18.1.1.2.
Calling Format
PROCEDURE SAR_CLOSE_OUTPUT
(WRITE_PACKET_ADDRESS: WORD MACHINE POINTER)
IMPORTED ('SAR$CLOSO$PG');
Returns
SAR_CLOSE_OUTPUT returns the calling status in the WRITE packet field
CALL_STATUS. If the status is S'Normal', then the close was successful.
If the status returned from SAR_CLOSE_OUTPUT is not S'Normal', then an error has
occurred and CALL_STATUS contains the status code. See 18.1.4 for a list of WRITE
function status codes.
7833 1733–004 18–17

SAR$ WRITE
18.1.3.5. Example
The following example shows a PLUS program using SAR$ WRITE to write SDF output:
COPY (‘SAR$DEFN’);
COPY (‘SAR$WPKTD’);
COPY (‘SAR$FILEPKTD’);
DECLARE WRITE_PKT: SAR_WRITE_PACKET,
IO_BUF: SAR_IO_BUFFER,
IMAGE_BUF: SAR_IMAGE_BUFFER,
TEXT_BUF: SAR_TEXT_BUFFER,
ATTRIBUTE_TBL: SAR_ATTRIBUTE_TABLE,
FILE_PKT: SAR_FILE_INFO_PACKET;
COPY (‘SAR$WRITE$DG’);
.
.
.
WRITE_PKT.PACKET_VERSION:= SAR_WRITE_PACKET_CURRENT_VERSION;
WRITE_PKT.OUTPUT_FILE_INFO_PACKET_ADDRESS:= LOC(FILE_PKT);
WRITE_PKT.OUTPUT_BUFFER_ADDRESS:= LOC(IO_BUF);
WRITE_PKT.OUTPUT_BUFFER_WORD_LENGTH:= SAR_IO_BUFFER_WORD_LENGTH;
WRITE_PKT.IMAGE_BUFFER_ADDRESS:= LOC(IMAGE_BUF);
WRITE_PKT.IMAGE_BUFFER_WORD_LENGTH:= SAR_IMAGE_BUFFER_WORD_LENGTH;
WRITE_PKT.TEXT_BUFFER_ADDRESS:= LOC(TEXT_BUF);
WRITE_PKT.TEXT_BUFFER_BYTE_LENGTH:= SAR_TEST_BUFFER_BYTE_LENGTH;
WRITE_PKT.ATTRIBUTE_TABLE_ADDRESS:= LOC(ATTRIBUTE_TBL);
WRITE_PKT.ATTRIBUTE_TABLE_WORD_LENGTH:= SAR_ATTRIBUTE_TABLE_WORD_LENGTH;
.
.
.
SAR_OPEN_OUTPUT(LOC(WRITE_PKT));
IF WRITE_PKT.CALL_STATUS NE S ‘Normal’
THEN BEGIN
PROCESS_WRITE_ERROR;
RETURN;
END;
.
.
.
SAR_WRITE(LOC(WRITE_PKT));
IF WRITE_PKT.CALL_STATUS NE S’Normal’
THEN BEGIN
PROCESS_WRITE_ERROR;
RETURN;
END;
.
.
.
SAR_CLOSE_OUPUT(LOC(WRITE_PKT));
IF WRITE_PKT.CALL_STATUS NE S ‘Normal’
THEN BEGIN
PROCESS_WRITE_ERROR;
RETURN;
END;
18–18 7833 1733–004

SAR$ WRITE
In this example, the COPY statement obtains the SAR$ definitions for the buffers and
tables, WRITE packet, WRITE procedure, and file information packet.
The SAR$ data structures for the WRITE function are declared by using the definitions
contained in element SAR$DEFN, SAR$WPKTD, and SAR$FILEPKTD.
The WRITE packet is initialized by assigning appropriate values to all necessary fields.
All other WRITE packet fields take the default values if the WRITE packet is zero-filled.
The SAR_WRITE_PACKET_CURRENT_VERSION constant is defined in the SAR$WPKTD
element, and the buffer length constants are defined in the SAR$DEFN element.
The WRITE function is initialized by calling the SAR_OPEN_OUTPUT procedure, passing
the WRITE packet address as a parameter. If the CALL_STATUS field of the WRITE
packet is not status S'Normal', the error is processed. The SAR_WRITE procedure is
called to write each SDF image out to the file or element described in the file information
packet.
When all images are written out, the SAR_CLOSE_OUTPUT procedure is called. This
procedure writes an end-of-file record, and if the output is to an element, adds the
element to the program file table of contents.
18.1.4. Status Lists for PLUS WRITE Procedures
The WRITE procedure call status codes listed in Table 18–3 may be returned to the
calling program in the CALL_STATUS field of the WRITE packet. These CALL_STATUS
codes are for SAR_WRITE_PACKET_CURRENT_VERSION = 2 and above. A list of all call
status codes is available as WRITE_CALL_STATUS_LIST, an 18-bit status data entity
defined in the element SAR$WPKTD.
Table 18–3. SAR$: WRITE Procedure CALL_STATUS Codes
Octal Code Status
0 Normal return from SAR$.
01 An outdated WRITE packet version is being used.
02 An invalid WRITE packet version is being used.
03 The value for IMAGE_BUFFER_ADDRESS is NULL; an address must be
given for the output image buffer.
04 The IMAGE_BUFFER_WORD_LENGTH is zero; a length must be given for
the output image buffer.
05 The value for OUTPUT_FILE_INFO_PKT_ADDRESS is NULL; a file
information packet must be given for this output file type.
06 An invalid value is specified for OUTPUT_FILE_TYPE.
07 An invalid value is specified for OUTPUT_LINE_NUMBER_TYPE.
010 An invalid value is specified for UNTRANSLATE_MODE.
7833 1733–004 18–19

SAR$ WRITE
Table 18–3. SAR$: WRITE Procedure CALL_STATUS Codes
Octal Code Status
011 The value for OUTPUT_BUFFER_WORD_LENGTH is too small; use the word
length returned in RECOMMENDED_BUFFER_LENGTH.
012 An I/O error has occurred in a WRITE procedure. See the IO_STATUS_CODE
field for the status code and Table 18–4.
013 An invalid value is specified for OUTPUT_RECORD_TYPE.
014 An incorrect ACD subroutine version is being used with SAR$.
015 The attribute table contains an index that is either zero, not in sequential
order, or greater than the text length.
016 The attribute table contains an invalid attribute type or an invalid value for the
attribute type.
017 An illegal character set type is specified for the
OUTPUT_IMAGE_CHARACTER_TYPE.
020 Line numbers are not allowed for this output file type.
021 The WRITE packet is not initialized; a call to SAR_OPEN_OUTPUT must be
made before calls to SAR_WRITE, SAR_WRITE_CONTROL, or
SAR_CLOSE_OUTPUT.
022 The image buffer has overflowed; use the word length in
RECOMMENDED_BUFER_LENGTH for IMAGE_BUFFER_WORD_LENGTH
and call SAR_WRITE again.
024 An error has occurred in adding the element to the table of contents; see the
SUB_STATUS_CODE field for the ER PFI$ status code and the Exec ER
Programming Reference Manual.
026 An error has occurred in executing the symbiont file closing breakpoint; see
the SUB_STATUS_CODE field for the ER CSF$ status code returned for
@SYM and @BRKPT in dynamically submitted control statements in the Exec
ER Programming Reference Manual.
027 SDF control records cannot be written to this output file type.
030 Symbiont write control records cannot be written to this output file type.
031 The file name buffer address in the FIP is NULL; an address of an SDF file
name must be specified.
032 The file name buffer address in the FIP is NULL; an address of a symbiont file
name must be specified.
033 The element name buffer address in the FIP is NULL; an address of an SDF
element name must be specified.
034 An illegal value is specified for the file name buffer byte length; legal values
are from 1 to 12.
035 An illegal value is specified for the element name buffer byte length; legal
values are from 1 to 12.
036 An illegal value is specified for the version name buffer byte length; legal
values are from 1 to 12.
18–20 7833 1733–004

Table 18–3. SAR$: WRITE Procedure CALL_STATUS Codes
Octal Code Status
SAR$ WRITE
037 The output I/O buffer address is NULL; this buffer must be provided when
writing to an SDF file or element.
0100 An unrecognized error has occurred in the SDFO routine. The SDFO error
code is returned in the SUB_STATUS field.
0101 An unrecognized error has occurred in an ACD subroutine. The ACD error
code is returned in the SUB_STATUS field.
0102 An unrecognized error has occurred in executing ER SYMB$. The SYMB$
error code is returned in the SUB_STATUS field.
0103 An incorrect SDFO packet version is being used. The correct SDFO packet
version is returned in the SUB_STATUS field.
0104 An incorrect ER SYMB$ packet version is being used. The correct SYMB$
packet version is returned in the SUB_STATUS field.
A CALL_STATUS code of 0100 or greater is an SAR$ internal error.
The WRITE procedure I/O status codes listed in Table 18–4 may be returned to the
calling program in the IO_STATUS field of the WRITE packet.
Table 18–4. SAR$: WRITE Procedure IO_STATUS Status List
Octal Code Status
0 Normal I/O status.
01 to 040 See Table C–2, I/O Status Codes, Exec ER Programming Reference Manual
for an explanation of the I/O status codes.
18.2. WRITE Function/MASM Interface
The SAR$ write function writes symbolic images to SDF files, SDF elements, and
symbiont files (PRINT$, PUNCH$, alternate PRINT$, and alternate PUNCH$). If an SDF
element is written to, the element is added to the program file table of contents when
the WRITE operation is completed (by calling S$ARCLOSO).
The SAR$ WRITE procedures can be called directly from MASM. The SAR$ data
structure definitions and procedure calls are defined by MASM procedures (PROCs).
The element SAR$PROCS contains these PROCs.
7833 1733–004 18–21

SAR$ WRITE
Empty symbiont output files may not be created by simply calling S$AROPENO followed
by S$ARCLOSO. An empty symbiont file may be created by setting SW$PCW to a
nonzero value when calling S$AROPENO, followed by a call to S$ARCLOSO. This will
cause a print control image to be generated, which will open the output file. If SW$PCW
is zero when creating an "empty" symbiont file, an error will occur during S$ARCLOSO.
18.2.1. WRITE Packet and Data Area Description
The SAR$ write function requires a WRITE packet and data area for the open-output,
write, and close-output calls. The S$ARWPDEF PROC generates the EQUFs defining
the packet fields. The word length of the MASM WRITE packet and data area is equal to
label SW$PKTWLEN defined by the S$ARWPDEF PROC (the current length is 70
words).
18.2.1.1. Required Information for WRITE Procedures
The calling program must set the following fields of the WRITE packet to appropriate
values:
SW$PKTVER
The WRITE packet data structure version. The current version is equal to the label
SW$CURVER, defined by the S$ARWPDEF PROC.
SW$FIPADDR
The address of the output file information packet. This packet is supplied by the
caller (see 16.1). Set this field to zero if SW$OUTFILT is 2, 3, or 6.
SW$OUTBUF
The address of the output buffer used to write images to the output file or element.
This field is defined only if output is to an SDF file or element. It is omitted if output
is to a symbiont file. Subsection 15.6.2 describes the output buffer.
SW$OUTBUFL
The length in words of the output buffer. It must be of length (28 * dpf * n), where
dpf is the disk prepping factor and n is a positive integer. This field is defined only if
output is to an SDF file or element. It is omitted if output is to a symbiont file.
SW$IMGBUF
The address of the output image buffer into which the SAR$ places the images to be
written out. Subsection 15.6.2 describes the image buffer.
SW$IMGBUFL
The length in words of the output image buffer.
18–22 7833 1733–004

SW$TEXBUF
SAR$ WRITE
The address of the output text buffer, into which the caller places the character text
to be written out. Subsection 15.6.2 describes the text buffer.
SW$TEXBUFL
The length in 9-bit bytes of the character text in the text buffer.
SW$ATTRIB
The address of the output attribute table into which the caller places the attributes
describing the character text to be output. This field is undefined if the
SW$ATTRIBL field is set to zero. Subsection 15.6.2 describes the format of the
attribute table.
SW$ATTRIBL
The number of valid entries in the attribute table (each entry is one word.) A value of
zero indicates there is no output attribute table.
SW$SDFICW
If the SW$OUTRECT field is set to 1 (SDF control record), the caller must place the
SDF image control word in this field, and place any data words of the control record
in the output text buffer.
18.2.1.2. Optional Information for WRITE Procedures
The calling program may optionally set the following fields of the WRITE packet. The
default values are obtained by zero-filling the WRITE packet before placing any
information in the packet.
SW$OUTFILT
The file type that output images are written to:
0 Write to an SDF element (default).
1 Write to an SDF file.
2 Write to the standard PRINT$ file.
3 Write to the standard PUNCH$ file.
4 Write to an alternate PRINT$ file.
5 Write to an alternate PUNCH$ file.
6 Construct the output image in the image buffer, but do not write it out.
The output file may not be a tape file.
7833 1733–004 18–23

SAR$ WRITE
SW$OUTRECT
The type of record to be written:
0 SDF data record for SDF files or elements (default).
1 SDF control record for SDF files or elements.
2 Data record for symbiont files.
3 Write control record for symbiont files.
SW$LNUMFMT
The format of line numbers used for output images:
0
1
2
3
4
SW$OCHART
No line numbers are to be written out (default).
Generate sequential fractional line numbers with initial value 10 and increment
value 10.
Generate sequential CTS line numbers with initial value 10 and increment value
10.
Output the fractional line numbers supplied by the caller in the packet.
Output the CTS line numbers supplied by the caller in the packet.
The character set type to be output by SAR$
0 ASCII/ISO 9-bit characters (default), including ASCII-like characters in Table H–1.
1 Attributed character data (ACD).
Other character set types may not be written out by SAR$. See 18.3 for details on
the allowed output character set types.
18–24 7833 1733–004

SW$ICHART
SAR$ WRITE
If the character set type of the text placed in the text buffer is Fieldata, this field
must be set to 1. Otherwise this field is set to 2 (ASCII/ISO–default). SAR$
converts Fieldata to ASCII/ISO before it is written out.
SW$UNTRFLG
The untranslate mode flag setting:
0
1
SW$SDFLBLF
An error is returned if character set types other than ASCII/ISO, ACD, or ASCIIlike
are specified for output (default).
Character set types other than ASCII/ISO, ACD, or ASCII-like are written to the
output file untranslated.
A flag controlling the generation of the SDF file or element label control record
0
1
SW$BRKPTF
If output is to an SDF file or element, write out a label control record with
general file type 'S' (default).
Do not write out an SDF label control record. If output is to an SDF file or
element, the caller must write this record.
A flag controlling symbiont file closing breakpoints:
0
1
SW$LINESPA
If output is to alternate symbiont file filename, execute a '@BRKPT filename'
command when the close-output procedure is called (default).
Do not execute a '@BRKPT filename' command.
For symbiont file output, the number of lines to space before writing the image
(default is 1).
7833 1733–004 18–25

SAR$ WRITE
SW$ELTCDT
For SDF element output, the creation date and time of the element to be entered in
the program file table of contents. The date and time format is described under
"Program File Format," Data Structures Programming Reference Manual. The default
is the current date and time when the close-output procedure is called.
SW$LNUMINT
The line number to be written out with the output image. It may be a CTS line
number or the integer part of a fractional line number (see SW$LNUMFMT). This
field is used only for output types of SDF files and SDF elements.
SW$LNUMF1
The first 10 digits of the fractional line number to be written out with the output
image. This field is used only for output types of SDF files and SDF elements.
SW$LNUMF2
The second 10 digits of the fractional line number to be written out with the output
image. This field is used only for output types of SDF files and SDF elements.
SW$LNUMF3
The third 10 digits of the fractional line number to be written out with the output
image. This field is used only for output types of SDF files and SDF elements.
SW$LNUMF4
The fourth 10 digits of the fractional line number to be written out with the output
image. This field is used only for output types of SDF files and SDF elements.
SW$TRIMBF
A flag that determines if words of blank (space) characters are trimmed from the end
of ASCII output images before they are written out.
0 Do not trim blank characters (default).
1 Trim blank characters from ASCII output images.
SW$PCW
The initial print or punch control width of the output file. The default is 33 words
(132 ASCII characters). This field is used only for symbiont output file types. This is
only recognized during the S$AROPENO call. If it is modified in subsequent calls to
S$ARWRITE, it will be ignored. If the output file type is a symbiont file, SAR$ may
expand the line width if necessary. The line width will be reset to the print or punch
device default in the S$ARCLOSO call. This is to allow for the additional bytes
required in the ASCII/ISO with embedded shift-coded kanji and ACD character types
and for transmitting large data records such as a full screen of characters.
18–26 7833 1733–004

18.2.1.3. Information Returned by WRITE Procedures
SAR$ WRITE
The following fields of the WRITE packet contain values returned by the SAR$ WRITE
procedures to the calling program:
SW$STATUS
The WRITE function status word; it contains the call status in H2, the substatus in
T1, and the I/O status in S3 of the word.
SW$CALLST
The status of the current open-output, write, or close-input procedure call. See Table
18–6 for an explanation of the octal status codes.
SW$IOSTAT
The status of any I/O operations performed by SAR$. See Table 18–7 for the octal
status codes.
SW$SYMBDT
The status word returned from an ER SYMB$ request. See the SYMB$ section,
Exec ER Programming Reference Manual for further details on the SYMB$ status
word.
SW$RECBUFL
The recommended buffer or table length when an invalid length is specified or when
an overflow occurs.
SW$IMGBLEN
The length in bytes of the image written out by the WRITE procedure. For images
written to SDF files or elements, the length does not include the image control word
or the length of the line number records. For images written to symbiont files, the
length is the number of bytes transferred by the SMB$ request.
SW$IMGSEC
The mass storage sector address that the SDF image was written to. This field is a
full word containing the sector address in S3 to S6 and the field SW$IMGWO in S1.
SW$IMGSEC is undefined if the output file type is not an SDF file or element. If a
line number control record (type 053) is written with the data record, this address is
the sector address of the line number control record corresponding to the data
record.
SW$IMGWO
The word offset into the sector address (SW$IMGSEC) that the SDF image was
written to. This field is contained in S1 of SW$IMGSEC. SW$IMGWO is undefined
if the output file type is not an SDF file or element.
7833 1733–004 18–27

SAR$ WRITE
18.2.1.4. WRITE Packet Definition PROC
The S$ARWPDEF PROC generates the EQUFs to define the WRITE packet. The calling
program may optionally attach an X-register and a B-register to these EQUFs. This
allows the calling program to allocate storage space for the WRITE packet either
statically at assembly time or dynamically at execution time. The calling program may
display the EQUF labels by setting the display-flag parameter on the PROC call. This
PROC also generates EQUs defining the WRITE packet current version and word length
at labels SW$CURVER and SW$PKTWLEN, respectively.
Calling Format
S$ARWPDEF x-reg,b-reg,dispflg
Parameters
x-reg
The X-register to be attached to the WRITE packet EQUFs. If it is omitted, no
X-register is attached to the EQUFs.
b-reg
The B-register to be attached to the WRITE packet EQUFs. If it is omitted, no
B-register is attached to the EQUFs.
dispflg
A flag to display a table of the WRITE packet EQUFs. If it is set to 'D', the field
names are displayed; otherwise, the field names are not displayed.
Example
$ASCII
$INCLUDE ‘MAXR$’
S$ARWPDEF X4,B6,‘D’
The PROC call S$ARWPDEF generates EQUFs using registers X4 and B6 and displays a
description of each packet field.
18–28 7833 1733–004

18.2.2. MASM WRITE Procedures Buffers and Tables
SAR$ WRITE
All buffers and tables must be provided by the calling program. The recommended
lengths for the buffers and tables are equated to labels in the S$ARWPDEF PROC.
These lengths and labels are listed in Table 18–5. These definitions simplify the creation
of required buffers and tables for the calling program.
Table 18–5. SAR$: MASM WRITE Buffer and Table
Lengths
Label Value
SW$OUTBUFDL (Output buffer word length) 448
SW$IMGBUFDL (Image buffer word length) 63
SW$TEXBUFDL (Text buffer byte length) 132
SW$ATTRIBDL (Attribute table word length) 40
18.2.3. WRITE Procedures Called from MASM
The procedures for the WRITE function are
• S$AROPENO (open output)
• S$ARWRITE (write an image)
• S$ARCLOSO (close output)
The calling sequences for these procedures are generated by MASM PROCs, contained
in the SYSLIB file (SYS$LIB$*SYSLIB) or SYS$*RLIB$.
18.2.3.1. Open-Output Procedure Call (S$AROPENO)
The WRITE packet and data area must be initialized before any images are written out.
The S$AROPENO PROC performs the WRITE packet initialization.
Initial Conditions
The calling program sets the following parameters in the WRITE packet to appropriate
values before calling S$AROPENO:
• Required parameters (described in 18.2.1.1)
SW$PKTVER
SW$OUTBUFL
W$FIPADDR
W$IMGBUF
W$OUTBUF
W$IMGBUFL
7833 1733–004 18–29

SAR$ WRITE
• Optional parameters (described in 18.2.1.2)
SW$OUTFILT
SW$UNTRFLG
SW$TRIMBF
SW$LNUMFMT
SW$SDFLBLF
SW$OCHART
SW$BRKPTF
Note: It is recommended that the calling program zero-fill the WRITE packet before
placing any parameters in the packet.
Calling Format
S$AROPENO wpkt
error return
normal return
where wpkt is a label identifying the starting address of the WRITE packet and data area.
Returns
If S$AROPENO takes the error return, A1 contains the call status code, A2 contains the
I/O status code, and A3 contains the substatus code. These status codes are also
returned in the packet fields SW$CALLST, SW$IOSTAT, and T1 of SW$STATUS,
respectively. See 18.2.4 for an explanation of the status codes.
If S$AROPENO takes the normal return, the initialization of the WRITE packet is
successful.
18.2.3.2. WRITE Procedure Call (S$ARWRITE)
The S$ARWRITE PROC writes images to the output file or element. Each call to
S$ARWRITE writes out one image. The calling program must supply the character text
of the image in the text buffer and the attributes for the text (if any) in the attribute table.
S$ARWRITE combines the text and attributes into the proper format and writes out the
image.
Initial Conditions
The calling program sets the following parameters in the WRITE packet to appropriate
values before calling S$ARWRITE:
• Required parameters (described in 18.2.1.1)
SW$TEXBUF
SW$ATTRIBL
SW$TEXBUFL
SW$ATTRIB
18–30 7833 1733–004

• Optional parameters (described in 18.2.1.2)
SW$OUTRECT
SW$LNUMINT
SW$LNUMF3
SW$ICHART
SW$LNUMF1
SW$LNUMF4
SW$LINESPA
SW$LNUMF2
Calling Format
S$ARWRITE wpkt
error return
normal return
SAR$ WRITE
where wpkt is a label identifying the starting address of the WRITE packet and data area.
Returns
If S$ARWRITE takes the error return, A1 contains the call status code, A2 contains the
I/O status code, and A3 contains the substatus code. These status codes are also
returned in the packet fields SW$CALLST, SW$IOSTAT, and T1 of SW$STATUS,
respectively. See 18.2.4 for an explanation of the status codes.
If S$ARWRITE takes the normal return, the write was successful. The following fields of
the WRITE packet contain information returned by SAR$ to the calling program:
SW$IMGBLEN
SW$IMGSEC
SW$IMGWO
These parameters are described in 18.2.1.3.
Write Control Functions
The calling program may perform write control functions with the S$ARWRITE
procedure call. The calling program sets SW$OUTRECT to 3 (write control record),
places the control image in the text buffer, and calls S$ARWRITE. See "Print Control
Function," Exec ER Programming Reference Manual for details on the control images.
18.2.3.3. Close-Output Procedure Call (S$ARCLOSO)
The S$ARCLOSO PROC performs the necessary tasks to close the output operation.
If the output type is an SDF element, the element is added to the program file table of
contents.
7833 1733–004 18–31

SAR$ WRITE
Initial Condition
The calling program may set the following optional parameter in the WRITE packet to an
appropriate value before calling S$ARCLOSO:
SW$ELTCDT
This parameter is described in 18.2.1.2.
Calling Format
S$ARCLOSO wpkt
error return
normal return
where wpkt is a label identifying the starting address of the WRITE packet and data area.
Returns
If S$ARCLOSO takes the error return, A1 contains the call status code, A2 contains the
I/O status code, and A3 contains the substatus code. These status codes are also
returned in the packet fields SW$CALLST, SW$IOSTAT, and T1 of SW$STATUS,
respectively. See 18.2.4 for an explanation of the status codes.
If S$ARCLOSO takes the normal return, the output is successfully closed.
18.2.4. Status Lists for MASM WRITE Procedures
The WRITE procedure call status codes listed in Table 18–6 may be returned to the
calling program in the SW$CALLST field of the WRITE packet. These call status codes
are for SW$CURVER = 2 or above.
Table 18–6. SAR$: WRITE Procedure SW$CALLST Codes
Octal Code Status
0 Normal return from SAR$.
01 An outdated WRITE packet version is being used.
02 An invalid WRITE packet version is being used.
03 The value for SW$IMGBUF is zero; an address must be given for the output
image buffer.
04 The SW$IMGBUFL is zero; a length must be given for the output image
buffer.
05 The value for SW$FIPADDR is zero; a file information packet must be given
for this output file type.
06 An invalid value is specified for SW$OUTFILT.
07 An invalid value is specified for SW$LNUMFMT.
010 An invalid value is specified for SW$UNTRFLG.
18–32 7833 1733–004

Table 18–6. SAR$: WRITE Procedure SW$CALLST Codes
Octal Code Status
SAR$ WRITE
011 The value for SW$OUTBUFL is too small; use the word length returned in
SW$RECBUFL.
012 An I/O error has occurred in a WRITE procedure. See the SW$IOSTAT field
for the status code and Table 18–7.
013 An invalid value is specified for SW$OUTRECT.
014 An incorrect ACD subroutine version is being used with SAR$.
015 The attribute table contains an index that is either zero, not in sequential
order, or greater than the text length.
016 The attribute table contains an invalid attribute type or an invalid value for the
attribute type.
017 An illegal character set type is specified in the SW$OCHART field.
020 Line numbers are not allowed for this output file type.
021 The WRITE packet is not initialized; a call to S$AROPENO must be made
before calls to S$ARWRITE or S$ARCLOSO.
022 The image buffer has overflowed; use the word length returned in
SW$RECBUFL for the SW$IMGBUFL field and call S$ARWRITE again.
024 An error has occurred in adding the element to the table of contents; see T1
of the SW$STATUS field for the ER PFI$ status code and the Exec ER
Programming Reference Manual.
026 An error has occurred in executing the symbiont file closing breakpoint; see
T1 of the SW$STATUS field for the ER CSF$ status code and the Exec ER
Programming Reference Manual.
027 SDF control records cannot be written to this output file type.
030 Symbiont write control records cannot be written to this output file type.
031 The file name buffer address in the FIP is zero; an address of an SDF file
name must be specified.
032 The file name buffer address in the FIP is zero; an address of a symbiont file
name must be specified.
033 The element name buffer address in the FIP is zero; an address of an SDF
element name must be specified.
034 An illegal value is specified for the file name buffer byte length in the FIP;
legal values are from 1 to 12.
035 An illegal value is specified for the element name buffer byte length in the
FIP; legal values are from 1 to 12.
036 An illegal value is specified for the version name buffer byte length in the FIP;
legal values are from 1 to 12.
037 The output I/O buffer address (SW$OUTBUF) is zero; this buffer must be
provided when writing to an SDF file or element.
7833 1733–004 18–33

SAR$ WRITE
Table 18–6. SAR$: WRITE Procedure SW$CALLST Codes
Octal Code Status
0100 An unrecognized error has occurred in the SDFO routine. The SDFO error
code is returned in the SUB_STATUS field.
0101 An unrecognized error has occurred in an ACD subroutine. The ACD error
code is returned in the SUB_STATUS field.
0102 An unrecognized error has occurred in executing ER SYMB$. The SYMB$
error code is returned in the SUB_STATUS field.
0103 An incorrect SDFO packet version is being used. The correct SDFO packet
version is returned in the SUB_STATUS field.
0104 An incorrect ER SYMB$ packet version is being used. The correct SYMB$
packet version is returned in the SUB_STATUS field.
A SW$CALLST code of 0100 or greater is a SAR$ internal error.
The WRITE procedure I/O status codes listed in Table 18–7 may be returned to the
calling program in the SW$IOSTAT field of the WRITE packet.
Table 18–7. SAR$: WRITE Procedure SW$IOSTAT Status List
Octal Code Status
0 Normal I/O status.
01 to 040 See the Exec ER Programming Reference Manual for an explanation of the
I/O status codes.
18.3. WRITE Function Supported Character Set
Types
Table H–1 lists 64 character set types defined for the OS 2200 system. Forty of these
are referred to as ASCII-like. This means that the character set is essentially identical to
the ASCII/ISO character set in the octal range 000 through 0177, with any differences
being minor. Table H–1 identifies the character set types that are ASCII-like.
Throughout this section, wherever ASCII or ASCII/ISO is used, the SAR$ capabilities
apply equally to all ASCII-like character sets.
The following character set types may be written to output files:
• ASCII-like characters, including ASCII/ISO 9-bit characters and ASCII/ISO 9-bit
characters with embedded shift-coded kanji
• Attributed character data (ACD)
18–34 7833 1733–004

18.3.1. ASCII/ISO and ASCII-like
SAR$ WRITE
If the text to be written out is in the ASCII/ISO character set, it is placed in the text
buffer. An attribute table is not necessary; the attribute table word length is set to zero.
18.3.2. ASCII/ISO with Embedded Shift-Coded Kanji
If the text to be written out already contains the embedded shift-code bytes, it is placed
in the text buffer. An attribute table is not necessary; the attribute table word length is
set to zero.
If the text to be written out is in internal format, the text part is placed in the text buffer,
and the attributes are placed in the attribute table. The WRITE procedure places the
shift-code bytes in the image before it is written out. Subsection 16.2 describes internal
format.
Multiple Block Sequence Indicator
If the multiple block sequence indicator is set in the last shift code of a record, the next
physical record is treated as a part of the current record. A complete record is returned
with the requested attribute table.
18.3.3. Attributed Character Data
The text to be written out must be in internal format. The text part is placed in the text
buffer, and the attributes are placed in the attribute table. The WRITE procedure
constructs the ACD image and writes it out. Subsection 16.2 describes internal format.
The Data Structures Programming Reference Manual describes the ACD format.
7833 1733–004 18–35

SAR$ WRITE
18–36 7833 1733–004

Section 19
SAR$ ATREAD
19.1. ATREAD Function/PLUS Interface
The SAR$ ATREAD function writes a symbolic image to the current output stream and
reads a symbolic image from the current input stream.
The SAR$ ATREAD procedures can be called directly from PLUS. All SAR$ data
structure definitions and procedure calls are contained in definition elements and may be
obtained with the PLUS COPY statement.
19.1.1. ATREAD Packet Data Structure Description
The SAR$ ATREAD function requires an ATREAD packet data structure for the
SAR_INITIALIZE_ATREAD and SAR_ATREAD procedure calls.
The type definition for this data structure is contained in the element SAR$ATRPKTD in
the SYSLIB file (SYS$LIB$*SYSLIB) or SYS$*RLIB$. It may be obtained with the COPY
statement. The identifier for the ATREAD packet data structure type is
SAR_ATREAD_PACKET.
The calling program must provide storage space for the ATREAD packet data structure,
plus any necessary buffers and tables, since SAR$ does not have any D-bank storage.
The length of the ATREAD packet is equal to the constant
SAR_ATREAD_PACKET_WORD_LENGTH, defined in the element SAR$ATRPKTD
(current length is 29 words). SAR_ATREAD_PACKET is defined as LOCATABLE.
The calling program places information in the ATREAD packet data structure and passes
the address of the data structure to SAR$ through the procedure calls.
7833 1733–004 19–1

SAR$ ATREAD
19.1.1.1. Required Information for ATREAD Procedures
The calling program must set the following fields of the ATREAD packet to appropriate
values:
PACKET_VERSION:
PLUS Attribute: 6-bit integer
The ATREAD packet data structure version. The current version is equal to the
constant SAR_ATREAD_PACKET_CURRENT_VERSION defined in the element
SAR$ATRPKTD.
IMAGE_BUFFER_ADDRESS:
PLUS Attribute: word pointer
The address of the image buffer which ATREAD uses to construct images to be
written out and to read input images into.
IMAGE_BUFFER_WORD_LENGTH:
PLUS Attribute: 18-bit integer
The length in words of the image buffer.
OUTPUT_TEXT_BUFFER_ADDRESS:
PLUS Attribute: word pointer
The address of the output text buffer into which the caller places the character text
to be written out.
OUTPUT_TEXT_BUFFER_BYTE_LENGTH:
PLUS Attribute: 18-bit integer
The length in 9-bit bytes of the character text in the text buffer.
OUTPUT_ATTRIBUTE_TABLE_ADDRESS:
PLUS Attribute: word pointer
The address of the output attribute table into which the caller places the attributes
describing the character text to be output. This field is undefined if the
OUTPUT_ATTRIBUTE_TABLE_WORD_LENGTH is zero.
19–2 7833 1733–004

OUTPUT_ATTRIBUTE_TABLE_WORD_LENGTH:
PLUS Attribute: 18-bit integer
SAR$ ATREAD
The number of valid entries in the attribute table. (Each entry is one word.) A value
of zero indicates there is no output attribute table.
INPUT_TEXT_BUFFER_ADDRESS:
PLUS Attribute: word pointer
The address of the input text buffer into which ATREAD places the character text of
the image read.
INPUT_TEXT_BUFFER_BYTE_LENGTH:
PLUS Attribute: 18-bit integer
The length in 9-bit bytes of the input text buffer.
INPUT_ATTRIBUTE_TABLE_ADDRESS:
PLUS Attribute: word pointer
The address of the input attribute table into which ATREAD places the attributes
describing the character text of the image read. This field is undefined if the
INPUT_ATTRIBUTE_TABLE_WORD_LENGTH is zero.
INPUT_ATTRIBUTE_TABLE_WORD_LENGTH:
PLUS Attribute: 18-bit integer
The length in words of the input attribute table. A length of zero indicates there is no
input attribute table.
19.1.1.2. Optional Information for ATREAD Procedures
The calling program may optionally set the following fields of the ATREAD packet. The
default values are obtained by zero-filling the ATREAD packet before placing any
information in the packet.
OUTPUT_CHARACTER_TYPE
PLUS Attribute: 6-bit status
The character set type of the image to be output by ATREAD:
S'ASCII_ISO' ASCII/ISO 9-bit characters (default).
S'ACD' Attributed character data (ACD).
A value of any ASCII-like character set type in Table H–1.
7833 1733–004 19–3

SAR$ ATREAD
Other character set types may not be written out by SAR$. See18.3 for details on
the allowed output character set types.
OUTPUT_IMAGE_LINE_SPACING
PLUS Attribute: 18-bit integer
The number of lines to space before writing the image (default is 1).
INPUT_SELECT_LIST_ADDRESS
PLUS Attribute: word pointer
The address of the input select list that specifies which attributes of the input image
to return to the caller. This field is undefined if
INPUT_SELECT_LIST_BYTE_LENGTH is zero.
INPUT_SELECT_LIST_BYTE_LENGTH
PLUS Attribute: 18-bit integer
The length in 9-bit bytes of the input select list. A length of zero indicates there is no
input select list (default).
INPUT_REQUEST_TYPE
PLUS Attribute: 6-bit status
The requested type of input:
S'Pass_embedded_KANJI'
Do not search for embedded shift-coded kanji in ASCII/ISO (default).
S'Translate_embedded_KANJI'
Search for any embedded shift-coded kanji in ASCII/ISO input and convert it into
internal format (text part and attributes part).
PRINT_CONTROL_WIDTH
PLUS Attribute: 18-bit integer
The number of words in which to set the print line width. This value may be
determined by dividing the desired number of columns by the constant
SAR_PCW_CHARS_PER_WORD. This value must be set prior to calling the
SAR_INITIALIZE_ATREAD routine. If this field is not set, the print line width will not
be changed by the SAR_INITIALIZE_ATREAD routine (it may still be changed by the
SAR_ATREAD routine if an image is encountered which is greater than the current
print line width). Following the call to the SAR_INITIALIZE_ATREAD, this field is
used to keep track of the current print line width; therefore, the caller should not
modify this field following the SAR_INITIALIZE_ATREAD routine.
19–4 7833 1733–004

19.1.1.3. Information Returned by ATREAD Procedures
The following fields of the ATREAD packet contain values returned by the SAR$
ATREAD procedures to the calling program:
CALL_STATUS
PLUS Attribute: 18-bit status
SAR$ ATREAD
The status of the current call to SAR_INITIALIZE_ATREAD or SAR_ATREAD. See
Table 19–3 for an explanation of the ATREAD procedure call status codes. This field
may also be referenced as an 18-bit logical field with label CALL_STATUS_CODE.
SUB_STATUS_CODE
PLUS Attribute: 6-bit logical
This field contains additional information for particular CALL_STATUS codes.
IO_STATUS
PLUS Attribute: 6-bit status
The status of any I/O operations performed by the ATREAD procedures. See
Table 19–3 for the I/O status lists. This field may also be referenced as a 6-bit logical
field with label IO_STATUS_CODE.
ATREAD_STATUS_WORD
PLUS Attribute: word logical
A one-word combination of CALL_STATUS, SUB_STATUS, and IO_STATUS
contained in H2, S1, and S3, respectively.
SYMB_STATUS_WORD
PLUS Attribute: word logical
The status word returned from an ER SYMB$ request.
See SYMB$, Exec ER Programming Reference Manual for further details on the ER
SYMB$ status word.
RECOMMENDED_BUFFER_LENGTH
PLUS Attribute: 18-bit integer
The recommended buffer or table length when an invalid length is specified or when
an overflow occurs.
7833 1733–004 19–5

SAR$ ATREAD
OUTPUT_IMAGE_BYTE_LENGTH
PLUS Attribute: 18-bit integer
The length in bytes of the image written out by SAR_ATREAD.
BYTE_LENGTH_OF_INPUT_TEXT
PLUS Attribute: 18-bit integer
The length in 9-bit bytes of the character text returned in the input text buffer.
NUMBER_OF_INPUT_ATTRIBUTES
PLUS Attribute: 18-bit integer
The number of attributes returned in the input attribute table.
INPUT_CHARACTER_TYPE
PLUS Attribute: 6-bit status
The character set type of the image read:
S'ASCII_ISO' ASCII/ISO 9-bit characters
S'ACD' Attributed character data (ACD)
A value of any ASCII-like character set type defined in Table H–1.
If a Fieldata image is read, it is translated to ASCII/ISO before being returned to the
caller. See 17.3 for details on allowed input character set types.
INPUT_CHARACTER_CODE
PLUS Attribute: 6-bit logical
The character set type of the image read:
01 ASCII/ISO 9-bit characters
077 Attributed character data (ACD)
A value of any ASCII-like character set type defined in Table H–1.
If a Fieldata image is read, it is translated to ASCII/ISO before being returned to the
caller. See 17.3 for details on allowed input character set types.
19–6 7833 1733–004

19.1.2. PLUS ATREAD Procedures Buffers and Tables
SAR$ ATREAD
All buffers and tables must be provided by the calling program. The type definitions for
the buffers and tables, and definitions for the default buffer and table lengths, are
contained in the element SAR$DEFN in the SYSLIB file (SYS$LIB$*SYSLIB) or
SYS$*RLIB$. They may be obtained with the COPY statement. The buffers and tables
for the ATREAD function are similar to the buffers and tables for the READ and WRITE
functions. See 17.1.2 and 18.1.2 for details on the buffers and tables.
The default buffer and table lengths are listed in Table 19–1.
Table 19–1. SAR$: PLUS ATREAD Buffer and Table
Length Defaults
Identifier Value
SAR_IO_BUFFER_WORD_LENGTH 448
SAR_IMAGE_BUFFER_WORD_LENGTH 63
SAR_TEXT_BUFFER_BYTE_LENGTH 132
SAR_ATTRIBUTE_TABLE_WORD_LENGTH 40
SAR_SELECT_LIST_BYTE_LENGTH 4
The buffer and table type definitions are listed in Table 19–2.
Table 19–2. SAR$: PLUS ATREAD Buffer and Table
Type Definitions
Identifier Type
SAR_IO_BUFFER 448 words logical locatable
SAR_IMAGE_BUFFER 63 words logical locatable
SAR_TEXT_BUFFER 132 ASCII characters locatable
SAR_ATTRIBUTE_TABLE 40 words logical locatable
SAR_SELECT_LIST 4 bytes logical locatable
The element SAR$DEFN also contains other definitions necessary to SAR$.
7833 1733–004 19–7

SAR$ ATREAD
19.1.3. ATREAD Procedures Called from PLUS
The procedures for the ATREAD function are
• SAR_INITIALIZE_ATREAD
• SAR_ATREAD
• SAR_RESTORE_ATREAD
The procedure declarations for SAR_INITIALIZE_ATREAD, SAR_ATREAD, and
SAR_RESTORE_ATREAD are contained in the element SAR$ATR$DG in the SYSLIB file
SYS$LIB$*SYSLIB. This element may be obtained with the COPY statement.
SAR$ATR$DG contains all three procedure declarations. All of the ATREAD procedure
modules are compiled with the G option using the IBJ$ calling sequence.
19.1.3.1. SAR_INITIALIZE_ATREAD Procedure Call
The ATREAD packet data structure must be initialized before calling SAR_ATREAD. The
SAR_INITIALIZE_ATREAD procedure performs the ATREAD packet initialization.
Initial Conditions
The calling program sets the following parameters in the ATREAD packet to appropriate
values before calling SAR_INITIALIZE_ATREAD:
• Required parameters (described in 19.1.1.1)
PACKET_VERSION
IMAGE_BUFFER_ADDRESS
IMAGE_BUFFER_WORD_LENGTH
• Optional parameters (described in 19.1.1.2)
INPUT_SELECT_LIST_ADDRESS
NPUT_SELECT_LIST_BYTE_LENGTH
NPUT_REQUEST_TYPE
PRINT_CONTROL_WIDTH
Note: The caller should zero-fill the ATREAD packet before placing any parameters in
the packet.
Calling Format
PROCEDURE SAR_INITIALIZE_ATREAD
(ATREAD_PACKET_ADDRESS: WORD MACHINE POINTER)
IMPORTED ('SAR$INATR$PG');
Returns
SAR_INITIALIZE_ATREAD returns the initialization status in the packet in CALL_STATUS.
If the status is S'Normal', the initialization of the ATREAD packet is successful.
Otherwise an error has occurred and CALL_STATUS contains the status code.
See 19.1.4 for the ATREAD function status code lists.
19–8 7833 1733–004

19.1.3.2. SAR_ATREAD Procedure Call
SAR$ ATREAD
The SAR_ATREAD procedure constructs an image from the output text and output
attributes, writes the image to the current output stream, reads an image from the
current input stream, and returns the character text and attributes of the image to the
calling program.
Initial Conditions
The calling program sets the following parameters in the packet to appropriate values
before calling SAR_ATREAD:
• Required parameters (described in 19.1.1.1)
OUTPUT_TEXT_BUFFER_ADDRESS
OUTPUT_TEXT_BUFFER_BYTE_LENGTH
OUTPUT_ATTRIBUTE_TABLE_ADDRESS
OUTPUT_ATTRIBUTE_TABLE_WORD_LENGTH
INPUT_TEXT_BUFFER_ADDRESS
INPUT_TEXT_BUFFER_BYTE_LENGTH
INPUT_ATTRIBUTE_TABLE_ADDRESS
INPUT_ATTRIBUTE_TABLE_WORD_LENGTH
• Optional parameters (described in 19.1.1.2)
OUTPUT_CHARACTER_TYPE
OUTPUT_IMAGE_LINE_SPACING
Calling Format
PROCEDURE SAR_ATREAD
(ATREAD_PACKET_ADDRESS: WORD MACHINE POINTER)
IMPORTED (‘SAR$ATR$PG’);
Returns
SAR_ATREAD returns the calling status in the ATREAD packet field CALL_STATUS.
If the status is S'Normal', then the call was successful. Following is the information
returned by SAR$ to the caller:
• Character text
The address of the character text and the length in 9-bit bytes (characters) are
returned in the fields INPUT_TEXT_BUFFER_ADDRESS and
BYTE_LENGTH_OF_INPUT_TEXT, respectively.
• Character type
The character set type of the image read is returned in the field
INPUT_CHARACTER_TYPE. The octal code of the character set type is returned in
the field INPUT_CHARACTER_CODE.
7833 1733–004 19–9

SAR$ ATREAD
• Attributes
The address of the attribute table and the number of entries are returned in the
fields INPUT_ATTRIBUTE_TABLE_ADDRESS and NUMBER_OF_INPUT
ATTRIBUTES, respectively.
SAR_ATREAD does not space-fill the input text buffer if the input character text length is
less than the length of the input text buffer. If the input character text length is greater
than the length of the input text buffer, then SAR_ATREAD truncates the character text
and returns an error status to the calling program.
If an end-of-file condition is encountered by SAR_ATREAD, the CALL_STATUS field of
the ATREAD packet is set to status S'End_of_file'.
If the status returned from SAR_ATREAD is not S'Normal' or S'End_of_file', then an
error has occurred and CALL_STATUS contains the status code. See 19.1.4 for a list of
ATREAD function status codes.
Note: SAR$ may expand the line width if necessary. The line width may be reset to
the print device default by calling the SAR_RESTORE_ATREAD procedure. The
expansion of the line width is to allow for the additional bytes required in the ASCII/ISO
with embedded shift-coded KANJI and ACD character types, and for transmitting large
data records, such as a full screen of characters.
19–10 7833 1733–004

19.1.4. SAR_RESTORE_ATREAD Procedure Call
SAR$ ATREAD
The SAR_RESTORE_ATREAD procedure restores the caller's environment, if it was
changed by SAR_ATREAD. Specifically, if SAR_ATREAD changed the print line width,
SAR_RESTORE_ATREAD will reset the print line width to the device default.
There are no required packet parameters for the SAR_RESTORE_ATREAD call.
However, SAR_RESTORE_ATREAD expects that a prior call to the
SAR_INITIALIZE_ATREAD routine was made.
Calling Format
PROCEDURE SAR_RESTORE_ATREAD
(ATREAD_PACKET_ADDRESS: WORD MACHINE POINTER)
IMPORTED (‘SAR$RSATR$PG’);
Returns
SAR_RESTORE_ATREAD returns the calling status in the ATREAD packet field,
CALL_STATUS. If the status is S'Normal', then the call was successful.
If the status returned from SAR_RESTORE_ATREAD is not S'Normal', then an error has
occurred, and CALL_STATUS contains the status code. See 19.1.5 for a list of ATREAD
function status codes.
19.1.5. Status Lists for PLUS ATREAD Procedures
The ATREAD procedure call status codes listed in Table 19–3 may be returned to the
calling program in the CALL_STATUS field of the ATREAD packet. These CALL_STATUS
codes are for SAR_ATREAD_PACKET_CURRENT_VERSION = 1 and above. A list of all
call status codes is available as ATREAD_CALL_STATUS_LIST, an 18-bit status data
entity defined in the element SAR$ATRPKTD.
Table 19–3. SAR$: ATREAD Procedure CALL_STATUS Codes
Octal Code Status
0 Normal return from the ATREAD procedure.
01 End-of-file condition reached by SAR_ATREAD.
02 An I/O error has occurred in an ATREAD procedure. See the
IO_STATUS_CODE field for the status code.
03 An outdated ATREAD packet version is being used.
04 An invalid ATREAD packet version is being used.
05 The ATREAD packet is not initialized; a call to SAR_INITIALIZE_ATREAD
must be made before calling SAR_ATREAD.
06 The value for IMAGE_BUFFER_ADDRESS is NULL; an address must be
given for the input image buffer.
7833 1733–004 19–11

SAR$ ATREAD
Table 19–3. SAR$: ATREAD Procedure CALL_STATUS Codes
Octal Code Status
07 The IMAGE_BUFFER_WORD_LENGTH is zero; a length must be given for
the input image buffer.
010 The value for OUTPUT_TEXT_BUFFER_ADDRESS is NULL; an address must
be given for the output text buffer.
011 The OUTPUT_TEXT_BUFFER_BYTE_LENGTH is zero; a length must be given
for the output text buffer.
012 The value for INPUT_TEXT_BUFFER_ADDRESS is NULL; an address must be
given for the input text buffer.
013 The INPUT_TEXT_BUFFER_BYTE_LENGTH is zero; a length must be given
for the input text buffer.
014 An invalid value is specified for the INPUT_REQUEST_TYPE field.
015 An illegal character set type is specified for the
OUTPUT_CHARACTER_TYPE.
016 The character set type of the input image is invalid.
017 The input or output image is too long to fit in the image buffer. The image
buffer word length necessary to hold the entire image is returned in the field
RECOMMENDED_BUFFER_LENGTH.
020 The character text is too long to fit in the input text buffer and has been
truncated. The text buffer byte length necessary to hold the character text is
returned in the field RECOMMENDED_BUFFER_LENGTH.
021 The number of attributes is too large to fit in the input attribute table. The
attribute table word length necessary to hold all the attributes is returned in
the field RECOMMENDED_BUFFER_LENGTH.
022 An incorrect internal format to ACD translation routine version is being used.
023 An incorrect ACD to internal format translation routine version is being used.
024 The output attribute table contains an index that is either zero, not in
sequential order, or greater than the output text length.
025 The output attribute table contains an invalid attribute type or an invalid value
for an attribute type.
026 The image read contains incorrectly formatted ACD or incorrectly formatted
embedded shift-coded kanji.
027 A partial image was read by SYMB$.
0100 An unrecognized error has occurred in an ACD subroutine. The ACD error
code is returned in the SUB_STATUS field.
0101 An unrecognized error has occurred in executing ER SYMB$. The SYMB$
error code is returned in the SUB_STATUS field.
0102 An incorrect ER SYMB$ packet version is being used. The correct SYMB$
packet version is returned in the SUB_STATUS field.
A CALL_STATUS code of 0100 or greater is a SAR$ internal error.
19–12 7833 1733–004

SAR$ ATREAD
The ATREAD procedure I/O status codes listed in Table 19–4 may be returned to the
caller in the IO_STATUS field of the ATREAD packet.
Table 19–4. SAR$: ATREAD Procedure IO_STATUS Status List
Octal Code Status
0 Normal I/O status.
01 to 040 See Table C–2, I/O Status Codes, Exec ER Programming Reference Manual
for an explanation of the I/O status codes.
19.2. ATREAD Function/MASM Interface
The SAR$ ATREAD function writes a symbolic image to the current output stream and
reads a symbolic image from the current input stream.
The SAR$ ATREAD procedures can be called directly from MASM. The SAR$ data
structure definitions and procedure calls are defined by MASM procedures (PROCs).
The element SAR$PROCS contains these PROCs.
19.2.1. ATREAD Packet and Data Area Description
The SAR$ READ function requires an ATREAD packet and data area for the INITIALIZE-
ATREAD and ATREAD calls.
The S$ARATRDEF PROC generates the EQUFs defining the ATREAD packet fields. The
word length of the MASM ATREAD packet and data area is at label SA$PKTWLEN
defined by the S$ARATRDEF PROC (the current length is 61 words).
19.2.1.1. Required Information for ATREAD Procedures
The calling program must set the following fields of the ATREAD packet to appropriate
values:
SA$PKTVER
The ATREAD packet data structure version. The current version is equal to the label
SA$CURVER defined by the S$ARATRDEF PROC.
SA$IMGBUF
The address of the image buffer which ATREAD uses to construct images to be
written out and to read input images into.
SA$IMGBUFL
The length in words of the image buffer.
7833 1733–004 19–13

SAR$ ATREAD
SA$OTEXTB
The address of the output text buffer, into which the caller places the character text
to be written out.
SA$OTEXTBL
The length in 9-bit bytes of the character text in the text buffer.
SA$OATTRT
The address of the output attribute table into which the caller places the attributes
describing the character text to be written out. This field is undefined if the output
attribute table word length is zero.
SA$OATTRTL
The number of valid entries in the attribute table. (Each entry is one word.) A value
of zero indicates there is no output attribute table.
SA$ITEXTB
The address of the input text buffer into which ATREAD places the character text of
the image read.
SA$ITEXTBL
The length in 9-bit bytes of the input text buffer.
SA$IATTRT
The address of the input attribute table into which ATREAD places the attributes
describing the character text of the image read. This field is undefined if the input
attribute table word length is zero.
SA$IATTRTL
The length in words of the input attribute table. A length of zero indicates that there
is no input attribute table.
19.2.1.2. Optional Information for ATREAD Procedures
The calling program may optionally set the following fields of the ATREAD packet.
The default values are obtained by zero-filling the ATREAD packet before placing any
information in the packet.
19–14 7833 1733–004

SA$OCHART
The character set type of the image to be output by ATREAD:
SAR$ ATREAD
0 ASCII/ISO 9-bit characters (default), including all ASCII-like types in Table H–1.
1 Attributed character data (ACD).
Other character set types may not be written out by ATREAD. See 18.3 for details
on the allowed output character set types.
SA$LINESPA
The number of lines to space before writing out the image (default is 1).
SA$ISLIST
The address of the input select list that specifies which attributes of the input image
to return to the caller. This field is undefined if the input select list byte length is
zero.
SA$ISLISTL
The length in 9-bit bytes of the input select list. A length of zero indicates that there
is no input select list (default).
SA$REQTYPE
The requested type of input:
0
1
SA$PCW
Do not search for embedded shift-coded kanji in ASCII/ISO (default)
Search for any embedded shift-coded kanji in ASCII/ISO input, and convert it into
internal format (text part and attributes part).
The number of words to set the print line width to. This value may be determined
by dividing the desired number of columns by the constant SA$PCW$CHARS. This
value must be set prior to calling S$ARINITATR. If this field is not set, the print line
width will not be changed by S$ARINITATR (it may still be changed by
S$ARATREAD if an image is encountered which is greater than the current print line
width). Following the call to S$ARINITATR, this field is used to keep track of the
current print line width; therefore, the caller should not modify this field following the
S$ARINITATR call.
7833 1733–004 19–15

SAR$ ATREAD
19.2.1.3. Information Returned by ATREAD Procedures
The following fields of the ATREAD packet contain values returned by the SAR$
ATREAD procedures to the calling program:
SA$STATUS
The ATREAD function status word; it contains the call status in H2, the substatus in
S1, and the I/O status in S3.
SA$CALLST
The status code of the INITIALIZE-ATREAD or ATREAD procedure call. See Table
19–6 for an explanation of the octal status codes.
SA$SUBSTAT
This field contains additional information for particular call status codes.
SA$IOSTAT
The status of any I/O operations performed by the ATREAD procedures. See Table
19–7 for the octal status codes.
SA$SYMBST
The status word returned from an ER SYMB$ request. See the SYMB$ section,
Exec ER Programming Reference Manual for further details on the SYMB$ status
word.
SA$RECBUFL
The recommended buffer or table length when an invalid length is specified or when
an overflow occurs.
SA$OIMGLEN
The length in bytes of the image written out by ATREAD.
SA$TEXTLEN
The length in 9-bit bytes of the character text returned in the text buffer.
SA$NUMATTR
The number of attributes returned in the attribute table.
19–16 7833 1733–004

SA$ICHART
The character set type of the image read:
01 ASCII/ISO 9-bit characters
077 Attributed character data (ACD)
A value of any ASCII-like character set type defined in Table H–1.
SAR$ ATREAD
If a Fieldata image is read, it is translated to ASCII/ISO before it is returned to the
caller. See 17.3 for details on allowed input character set types.
19.2.1.4. ATREAD Packet Definition PROC (S$ARATRDEF)
The S$ARATRDEF PROC generates the EQUFs to define the ATREAD packet. The
calling program may optionally attach an X-register and a B-register to these EQUFs.
This allows the calling program to allocate storage space for the ATREAD packet either
statically at assembly time or dynamically at execution time. The calling program may
display the EQUF labels by setting the display-flag parameter on the PROC call.
This PROC also generates EQUs defining the ATREAD packet current version and word
length at labels SA$CURVER and SA$PKTWLEN, respectively.
Calling Format
S$ARATRDEF x-reg,b-reg,dispflg
Parameters
x-reg
b-reg
dispflg
The X-register to be attached to the ATREAD packet EQUFs. If it is omitted, no
X-register is attached to the EQUFs.
The B-register to be attached to the ATREAD packet EQUFs. If it is omitted, no
B-register is attached to the EQUFs.
A flag to display a table of the ATREAD packet EQUFs. If it is set to 'D', the field
names are displayed; otherwise the field names are not displayed.
Example
$ASCII
$INCLUDE ‘MAXR$’
S$ARATRDEF X6,B3,‘D’
The PROC call S$ARATRDEF generates EQUFs using registers X6 and B3 and displays a
description of each packet field.
7833 1733–004 19–17

SAR$ ATREAD
19.2.1.5. ATREAD Packet Generation PROC (S$ARATRPKT)
The S$ARATRPKT PROC generates an ATREAD packet, and reserves space for an image
buffer, output text buffer, output attribute table, input text buffer, and input attribute
table. S$ARATRPKT also calls the S$ARATRDEF PROC, which defines the ATREAD
packet fields.
Calling Format
S$ARATRPKT x-reg,b-reg,dispflg
The parameters for S$ARATRPKT are the same as for the S$ARATRDEF PROC (see
19.2.1.4).
Returns
The S$ARATRPKT PROC places values in the following fields of the ATREAD packet:
SA$PKTVER SA$IMGBUF SA$IMGBUFL
SA$OTEXTB SA$OATTRT SA$ITEXTB
SA$ITEXTBL SA$ATTRT SA$IATTRTL
All other packet fields are set to default values. However, the calling program must still
place values in the SA$OTEXTBL and SA$OATTRTL fields before calling S$ARATREAD.
The generated buffers and tables use the default lengths (see Table 19–5). The
following externalized labels are used to reference the buffers and tables:
SAIMGBUF Image buffer
SAOTEXTB Output text buffer
SAOATTRT Output attribute table
SAITEXTB Input text buffer
SAIATTRT Input attribute table
19–18 7833 1733–004

19.2.2. MASM ATREAD Procedures Buffers and Tables
SAR$ ATREAD
All buffers and tables must be provided by the calling program. The recommended
lengths for the buffers and tables are equated to labels in the S$ARATRDEF PROC.
These lengths and labels are listed in Table 19–5. The buffers and tables for the
ATREAD function are similar to the buffers and tables for the READ and WRITE
functions. See 17.1.2 and 18.1.2 for details on the buffers and tables.
Table 19–5. SAR$: MASM ATREAD Buffer and
Table Lengths
Label Value
SA$IMGBUFDL (Image buffer word length) 63
SA$TEXBUFDL (Text buffer byte length) 132
SA$ATTRIBDL (Attribute table word length) 40
SA$SELLSTDL (Select list byte length) 4
19.2.3. ATREAD Procedures Called from MASM
The MASM procedures for the ATREAD function are
• S$ARINITATR (initialize ATREAD)
• S$ARATREAD (call ATREAD)
• S$ARRSATR (reset ATREAD)
19.2.3.1. Initialize ATREAD Procedure Call (S$ARINITATR)
The ATREAD packet and data area must be initialized before any calls are made to
ATREAD. The S$ARINITATR PROC performs the ATREAD packet initialization.
Initial Conditions
The calling program sets the following parameters in the ATREAD packet to appropriate
values before calling S$ARINITATR:
• Required parameters (described in 19.2.1.1)
SA$PKTVER
SA$IMGBUF
SA$IMGBUFL
7833 1733–004 19–19

SAR$ ATREAD
• Optional parameters (described in 19.2.1.2)
SA$ISLIST
SA$ISLISTL
SA$REQTYPE
SA$PCW
Note: It is recommended that the calling program zero-fill the ATREAD packet before
placing any parameters in the packet.
Calling Format
S$ARINITATR atrpkt
error return
normal return
where atrpkt is a label identifying the starting address of the ATREAD packet and data
area.
Returns
If S$ARINITATR takes the error return, A1 contains the call status code, A2 contains the
I/O status code, and A3 contains the substatus code. These status codes are also
returned in the packet fields SA$CALLST, SA$IOSTAT, and SA$SUBSTAT, respectively.
See 19.2.4 for an explanation of the status codes.
If S$ARINITATR takes the normal return, the initialization of the ATREAD packet is
successful.
19.2.3.2. ATREAD Procedure Call (S$ARATREAD)
The S$ARATREAD PROC constructs an image from the output text and output
attributes, writes the image to the current output stream, reads an image from the
current input stream, and returns the character text and attributes of the image to the
calling program.
Initial Conditions
The calling program sets the following parameters in the ATREAD packet to appropriate
values before calling S$ARATREAD:
• Required parameters (described in 19.2.1.1)
SA$OTEXTB
SA$OATTRTL
SA$IATTRT
SA$OTEXTBL
SA$ITEXTB
SA$IATTRTL
SA$OATTRT
SA$ITEXTBL
19–20 7833 1733–004

• Optional parameters (described in 19.2.1.2)
SA$OCHART
SA$LINESPA
Calling Format
S$ARATREAD atrpkt
error return
end-of-file return
normal return
SAR$ ATREAD
where atrpkt is a label identifying the starting address of the ATREAD packet and data
area.
Returns
error
If S$ARATREAD takes the error return, A1 contains the call status code, A2 contains
the I/O status code, and A3 contains the substatus code. These status codes are
also returned in the packet fields SA$CALLST, SA$IOSTAT, and SA$SUBSTAT,
respectively. See 19.2.4 for an explanation of the status codes.
end-of-file
normal
If S$ARATREAD takes the end-of-file return, the ATREAD request encountered an
end-of-file condition. A1 contains the call status code, A2 contains the I/O status
code, and A3 contains the substatus code. These status codes are also returned in
the packet fields SA$CALLST, SA$IOSTAT, and SS$SUBSTAT, respectively.
If S$ARATREAD takes the normal return, the ATREAD call was successful. The
following information is returned by ATREAD to the caller:
• Character text
The address of the character text and the length in 9-bit bytes (characters) are
returned in the fields SA$ITEXTB and SA$TEXTLEN, respectively.
• Character type
The character set type of the image read is returned in the field SA$ICHART.
• Attributes
The address of the attribute table and the number of entries are returned in the
fields SA$IATTRT and SA$NUMATTR, respectively.
7833 1733–004 19–21

SAR$ ATREAD
S$ARATREAD does not space-fill the input text buffer when the input character text
length is less than the length of the input text buffer. If the input character text length is
greater than the length of the input text buffer, S$ARATREAD truncates the character
text and returns an error status to the calling program.
Note: SAR$ may expand the line width, if necessary. The line width may be reset to
the print device default by calling the S$ARRSATR (restore ATREAD) procedure. The
expansion of the line width is to allow for the additional bytes required in the ASCII/ISO
with embedded shift-coded KANJI and ACD character types, and for transmitting large
data records, such as a full screen of characters
19.2.3.3. Reset ATREAD Procedure Call (S$ARRSATR)
The S$ARRSATR PROC restores the caller's environment, if it was changed by
S$ARATREAD. Specifically, if S$ARATREAD changed the print line width, S$ARRSATR
will reset the print line width to the device default.
There are no required packet parameters for the S$ARRSATR PROC call. However,
S$ARRSATR expects that a prior call to the S$ARINITATR PROC was made.
Calling format
S$ARRSATR atrpkt
error return
normal return
where atrpkt is a label identifying the start address of the ATREAD packet and data area.
Returns
If S$ARRSATR takes the normal return, the call was successful.
If S$ARRSATR takes the error return, A1 contains the call status code. This status code
is also returned in the packet field SA$CALLST. See 19.2.4 for an explanation of the
status codes.
19–22 7833 1733–004

19.2.4. Status Lists for MASM ATREAD Procedures
SAR$ ATREAD
The ATREAD procedure call status codes listed in Table 19–6 may be returned to the
calling program in the SA$CALLST field of the ATREAD packet. These call status codes
are for SA$CURVER = 1 and above.
Table 19–6. SAR$: ATREAD Procedure SA$CALLST Status Codes
Octal Code Status
0 Normal return from the ATREAD procedure.
01 End-of-file condition reached by S$ARATREAD.
02 An I/O error has occurred in an ATREAD procedure. See the SA$IOSTAT
field and Table 19–7 for the status code.
03 An outdated ATREAD packet version is being used.
04 An invalid ATREAD packet version is being used.
05 The ATREAD packet is not initialized; a call to S$ARINITATR must be made
before calling S$ARATREAD.
06 The value for SA$IMGBUF is zero; an address must be given for the image
buffer.
07 The value for SA$IMGBUFL is zero; a length must be given for the image
buffer.
010 The value for SA$OTEXTB is zero; an address must be given for the output
text buffer.
011 The value for SA$OTEXTBL is zero; a length must be given for the output
text buffer.
012 The value for SA$ITEXTB is zero; an address must be given for the input text
buffer.
013 The value for SA$ITEXTBL is zero; a length must be given for the input text
buffer.
014 An invalid value is specified for SA$REQTYPE.
015 An illegal character set type is specified for SA$OCHART.
016 The character set type of the input image is invalid.
017 The input or output image is too long to fit in the image buffer. The image
buffer word length necessary to hold the entire image is returned in the field
SA$RECBUFL.
020 The character text is too long to fit in the input text buffer and has been
truncated. The text buffer byte length necessary to hold the character text is
returned in the field SA$RECBUFL.
021 The number of attributes is too large to fit in the input attribute table. The
attribute table word length necessary to hold all the attributes is returned in
the field SA$RECBUFL.
022 An incorrect internal format to ACD translation routine version is being used.
023 An incorrect ACD to internal format translation routine version is being used.
7833 1733–004 19–23

SAR$ ATREAD
Table 19–6. SAR$: ATREAD Procedure SA$CALLST Status Codes
Octal Code Status
024 The output attribute table contains an index that is either zero, not in
sequential order, or greater than the output text length.
025 The output attribute table contains an invalid attribute type or an invalid value
for an attribute type.
026 The image read contains incorrectly formatted ACD or incorrectly formatted
embedded shift-coded kanji.
027 A partial image was read by SYMB$.
0100 An unrecognized error has occurred in an ACD subroutine. The ACD error
code is returned in the SA$SUBSTAT field.
0101 An unrecognized error has occurred in executing ER SYMB$. The SYMB$
error code is returned in the SA$SUBSTAT field.
0102 An incorrect ER SYMB$ packet version is being used. The correct SYMB$
packet version is returned in the SA$SUBSTAT field.
A SA$CALLST status code of 0100 or greater is an SAR$ internal error.
The ATREAD procedure I/O status codes listed in Table 19–7 may be returned to the
caller in the SA$IOSTAT field of the ATREAD packet.
Table 19–7. SAR$: ATREAD Procedure SA$IOSTAT Status Codes
Status code Explanation
0 Normal I/O status.
01 to 040 See Table C–2, I/O Status Codes, Exec ER Programming Reference Manual.
19–24 7833 1733–004

Section 20
SAR$ COM
20.1. SAR$ COM Function/PLUS Interface
The SAR$ COM function writes a symbolic image to the operator's console, and
optionally reads a symbolic image from the operator's console.
The SAR$ COM procedure can be called directly from PLUS. All SAR$ data structure
definitions and procedure calls are contained in definition elements and are obtained with
the PLUS COPY statement.
20.1.1. SAR$ COM Packet Data Structure Description
The SAR$ COM function requires a COM packet data structure for the SAR_COM
procedure call. The type definition for this data structure is contained in the element
SAR$COMPKTD in the SYSLIB file (SYS$LIB$*SYSLIB). This element may be obtained
with the PLUS COPY statement. The identifier for the SAR$ COM packet data structure
type is SAR_COM_PACKET.
The calling program must provide storage space for the SAR$ COM packet data
structure, plus any necessary buffers and tables, since SAR$ does not have any D-bank
storage. The length of the SAR$ COM packet is equal to the constant
SAR_COM_PACKET_WORD_LENGTH, defined in the element SAR$COMPKTD (current
length is 25 words). The SAR_COM_PACKET data structure is defined as LOCATABLE.
The calling program places information in the SAR$ COM packet data structure, and
passes the address of the data structure to the SAR$ COM function through the
procedure calls.
20.1.1.1. Required Information for SAR$ COM Procedure
The calling program must set the following fields of the SAR$ COM packet to
appropriate values:
PACKET_VERSION
PLUS Attribute: 6-bit integer
The SAR$ COM packet data structure version. The current version is equal to the
constant SAR_COM_PACKET_CURRENT_VERSION defined in the element
SAR$COMPKTD.
7833 1733–004 20–1

SAR$ COM
OUTPUT_TEXT_BUFFER_ADDRESS
PLUS Attribute: word pointer
The address of the output text buffer, which contains the character text of the image
that the SAR$ COM function writes out.
OUTPUT_TEXT_BUFFER_BYTE_LENGTH
PLUS Attribute: 18-bit integer
The length in 9-bit bytes of the character text in the text buffer. This is the number
of characters that the SAR$ COM function writes out.
INPUT_TEXT_BUFFER_ADDRESS
PLUS Attribute: word pointer
The address of the input text buffer, which contains the character text of the image
that the SAR$ COM function reads in. This field is not necessary if
INPUT_TEXT_BUFFER_BYTE_LENGTH is zero.
INPUT_TEXT_BUFFER_BYTE_LENGTH
PLUS Attribute: 18-bit integer
The length in 9-bit bytes of the input text buffer; this is the maximum number of
characters that the SAR$ COM function will read in. If this field is set to zero, no
input is solicited from the operator's console.
20.1.1.2. Optional Information for SAR$ COM Procedure
The calling program may optionally set the following fields of the COM packet. The
default values are obtained by zero-filling the COM packet before placing any information
in the packet.
OUTPUT_CHARACTER_TYPE
PLUS Attribute: 6-bit status
The character set type of the image written out by the SAR$ COM function.
S'ASCII_ISO' ASCII/ISO 9-bit characters (default).
S'ACD' Attributed character data (ACD)
20–2 7833 1733–004

A value of any ASCII-like character set type in Table H–1.
SAR$ COM
Other character set types may not be written out by the SAR$ COM function. See
18.3 for details on the allowed output character set types.
IMAGE_BUFFER_ADDRESS
PLUS Attribute: word pointer
The address of the image buffer; this buffer is necessary if either the output or input
image character set types are ASCII/ISO with embedded shift-coded kanji or ACD.
The default is no image buffer.
IMAGE_BUFFER_WORD_LENGTH
PLUS Attribute: 18-bit integer
The length in words of the image buffer; a length must be specified if an address is
given in IMAGE_BUFFER_ADDRESS. A length of zero indicates there is no image
buffer (default).
OUTPUT_ATTRIBUTE_TABLE_ADDRESS
PLUS Attribute: word pointer
The address of the output attribute table which contains the attributes that describe
the character text of the image that the SAR$ COM function writes out. If there are
no attributes for the output image, this table is not necessary. The default is no
output attribute table.
OUTPUT_ATTRIBUTE_TABLE_WORD_LENGTH
PLUS Attribute: 18-bit integer
The number of valid entries in the attribute table. (Each entry is one word.) A value
of zero indicates there is no output attribute table (default).
INPUT_ATTRIBUTE_TABLE_ADDRESS
PLUS Attribute: word pointer
The address of the input attribute table which contains the attributes that describe
the character text of the image that the SAR$ COM function reads in. If the input
image does not have any attributes, this table is not necessary. The default is no
input attribute table.
INPUT_ATTRIBUTE_TABLE_WORD_LENGTH
PLUS Attribute: 18-bit integer
The length in words of the input attribute table. A length of zero indicates there is
no input attribute table (default).
7833 1733–004 20–3

SAR$ COM
INPUT_SELECT_LIST_ADDRESS
PLUS Attribute: word pointer
The address of the input select list that specifies which attributes of the input image
to return to the caller. The default is no input select list.
INPUT_SELECT_LIST_BYTE_LENGTH
PLUS Attribute: 18-bit integer
The length in 9-bit bytes of the input select list. A length of zero indicates there is no
input select list (default).
INPUT_REQUEST_TYPE
PLUS Attribute: 6-bit status
The request type for the input image.
S'Pass_embedded_KANJI'
Do not search for embedded shift-coded kanji in input images of character set
type ASCII/ISO (default).
S'Translate_embedded_KANJI'-
Search ASCII/ISO input images for any embedded shift-coded kanji, and return
the image in internal format (text part and attributes part). This request type
requires an image buffer and an input attribute table.
CONSOLE_CLASS
PLUS Attribute: 6-bit status
The console class that the ER COM$ request is directed to:
S'System' System console (default).
S'IO_activity' I/O activity console.
S'Communications' Communications console.
S'Hardware_confidence' Hardware confidence console.
S'User_defined_4' Individual site-defined console for octal code 4.
S'User_defined_5' Individual site-defined console for octal code 5.
S'User_defined_6' Individual site-defined console for octal code 6.
S'User_defined_7' Individual site-defined console for octal code 7.
See the ER COM$ section, Exec ER Programming Reference Manual for further
details.
20–4 7833 1733–004

CONTROL_BITS
PLUS Attribute: 6-bit logical
SAR$ COM
The caller supplied control bits for the ER COM$ request (default is zero). See the
ER COM$ section, Exec ER Programming Reference Manual for further details.
ADDITIONAL_CONTROL_BITS
PLUS Attribute: 6-bit logical
The caller supplied additional control bits for the ER COM$ request. SAR$ COM
always sets bit 001 in addition to any caller supplied bits. See the ER COM$ section,
Exec ER Programming Reference Manual for further details.
RUN_ID_FOR_LOGGING
PLUS Attribute: 8 ASCII characters
The run-id to use when logging the console message. See the ER COM$ section,
Exec ER Programming Reference Manual for further details.
ROUTING_CONSOLE
PLUS Attribute: 8 ASCII characters
The console to which the message is sent. This definition is a legacy from Exec
levels prior to 40R1 and is supplied for compatability only. All currently supported
Exec levels use the ROUTING_INFORMATION definition, described below. See the
Exec ER Programming Reference Manual for further details.
ROUTING_INFORMATION
PLUS Attribute: 36-bit machine logical
This caller supplied routing information overlays the first 4 characters of
ROUTING_CONSOLE. This field should be used when the routing information to be
supplied for the ER COM$ request is either a 6-Fieldata character-site id or binary
information. See the ER COM$ section of the Exec ER Programming Reference
Manual for further details.
7833 1733–004 20–5

SAR$ COM
20.1.1.3. Information Returned by SAR$ COM Procedure
The following fields of the SAR$ COM packet contain values returned by the SAR$ COM
procedure to the calling program:
CALL_STATUS
PLUS Attribute: 18-bit status
The status of the current call to the SAR_COM procedure. See Table 20–3 for an
explanation of the SAR$ COM procedure call status codes. This field may also be
referenced as an 18-bit logical field with label CALL_STATUS_CODE.
SUB_STATUS_CODE
PLUS Attribute: 6-bit logical
This field contains additional information for particular CALL_STATUS codes.
COM_STATUS_WORD
PLUS Attribute: word logical
A one-word combination of CALL_STATUS and SUB_STATUS contained in H2 and
S1, respectively.
RECOMMENDED_BUFFER_LENGTH
PLUS Attribute: 18-bit integer
The recommended buffer or table length returned by the SAR$ COM function when
an invalid length is specified or when an overflow occurs.
OUTPUT_IMAGE_BYTE_LENGTH
PLUS Attribute: 18-bit integer
The length in bytes of the image written out by the SAR_COM procedure.
BYTE_LENGTH_OF_INPUT_TEXT
PLUS Attribute: 18-bit integer
The length in 9-bit bytes of the character text read from the operator's console and
returned in the input text buffer.
NUMBER_OF_INPUT_ATTRIBUTES
PLUS Attribute: 18-bit integer
The number of attributes returned in the input attribute table.
20–6 7833 1733–004

20.1.2. SAR$ PLUS COM Procedure Buffers and Tables
SAR$ COM
All buffers and tables must be provided by the calling program. The type definitions for
the buffers and tables and the definitions for the default buffer and table lengths are
contained in the element SAR$DEFN in the SYSLIB file (SYS$LIB$*SYSLIB) or
SYS$*RLIB$. This element is obtained with the COPY statement. The buffers and
tables for the COM function are similar to the buffers and tables for the READ and
WRITE functions. See 17.1.2 and 18.1.2 for details on the buffers and tables. Note that
for the COM function, the image buffer is not used if the input and output images do not
have character attributes.
The default buffer and table lengths are listed in Table 20–1.
Table 20–1. SAR$: PLUS COM Buffer and Table Length
Defaults
Identifier Value
SAR_IMAGE_BUFFER_WORD_LENGTH 63
SAR_TEXT_BUFFER_BYTE_LENGTH 132
SAR_ATTRIBUTE_TABLE_WORD_LENGTH 40
SAR_SELECT_LIST_BYTE_LENGTH 4
The buffer and table type definitions are listed in Table 20–2.
Table 20–2. SAR$: PLUS COM Buffer and Table Type Definitions
Identifier Type
SAR_IMAGE_BUFFER 63 words logical locatable
SAR_TEXT_BUFFER 132 ASCII characters locatable
SAR_ATTRIBUTE_TABLE 40 words logical locatable
SAR_SELECT_LIST 4 bytes logical locatable
The element SAR$DEFN also contains other definitions necessary to SAR$.
7833 1733–004 20–7

SAR$ COM
20.1.3. SAR$ COM Procedure Called from PLUS
The SAR$ COM function writes a symbolic image to the operator's console and
optionally reads a symbolic image from the operator's console.
The calling procedure for the COM function is SAR_COM.
The procedure declaration for SAR_COM is contained in the element SAR$COM$DG, in
the SYSLIB file (SYS$LIB$*SYSLIB) or SYS$*RLIB$. This element is obtained with the
COPY statement. The module containing the SAR_COM procedure uses the PLSSTACK
and is compiled with the G option using the IBJ$ calling sequence.
SAR_COM Procedure Call
The SAR_COM procedure constructs an image from the output text and output
attributes, writes the image to the operator's console, reads an image from the
operator's console, and returns the character text and attributes of the image to the
caller.
Initial Conditions
The calling program sets the following parameters in the packet to appropriate values
before calling SAR_COM:
• Required parameters (described in 20.1.1.1)
PACKET_VERSION
OUTPUT_TEXT_BUFFER_ADDRESS
OUTPUT_TEXT_BUFFER_BYTE_LENGTH
INPUT_TEXT_BUFFER_ADDRESS
INPUT_TEXT_BUFFER_BYTE_LENGTH
• Optional parameters (described in 20.1.1.2)
OUTPUT_CHARACTER_TYPE
INPUT_REQUEST_TYPE
IMAGE_BUFFER_ADDRESS
IMAGE_BUFFER_WORD_LENGTH
OUTPUT_ATTRIBUTE_TABLE_ADDRESS
OUTPUT_ATTRIBUTE_TABLE_WORD_LENGTH
INPUT_ATTRIBUTE_TABLE_ADDRESS
INPUT_ATTRIBUTE_TABLE_WORD_LENGTH
INPUT_SELECT_LIST_ADDRESS
INPUT_SELECT_LIST_BYTE_LENGTH
CONSOLE_CLASS
CONTROL_BITS
ADDITIONAL_CONTROL_BITS
RUN_ID_FOR_LOGGING
ROUTING_CONSOLE
ROUTING_INFORMATION
20–8 7833 1733–004

Calling Format
PROCEDURE SAR_COM(COM_PACKET_ADDRESS: WORD MACHINE POINTER)
IMPORTED (‘SAR$COM$PG’);
SAR$ COM
Returns
SAR_COM returns the calling status in the COM packet field CALL_STATUS. If the
status is S'Normal', then the call was successful. The following information is returned
by SAR$ to the calling program:
• Character text
If operator input was solicited, the address of the character text and the length in
9-bit bytes (characters) are returned in the fields INPUT_TEXT_BUFFER_ADDRESS
and BYTE_LENGTH_OF_INPUT_TEXT, respectively. The character set type of the
image read is the same as the output image character set type.
• Attributes
If operator input was solicited, the address of the input attribute table and the
number of entries are returned in the fields INPUT_ATTRIBUTE_TABLE_ADDRESS
and NUMBER_OF_INPUT ATTRIBUTES, respectively.
If the status returned from SAR_COM is not S'Normal' or S'End_of_file', then an error
has occurred and CALL_STATUS contains the status code. See 20.1.4 for a list of COM
function status codes.
20.1.4. Status Lists for PLUS COM Procedure
The COM procedure call status codes listed in Table 20–3 may be returned to the calling
program in the CALL_STATUS field of the COM packet. These CALL_STATUS codes are
for SAR_COM_PACKET_CURRENT_VERSION = 1 and above. A list of all call status
codes is available as COM_CALL_STATUS_LIST, an 18-bit status data entity defined in
the element SAR$COMPKTD.
Table 20–3. SAR$: COM Procedure CALL_STATUS Codes
Octal Code Status
0 Normal return from the SAR$ COM procedure.
01 An outdated SAR$ COM packet version is being used.
02 An invalid SAR$ COM packet version is being used.
03 The value for IMAGE_BUFFER_ADDRESS is NULL; an address must be
given for the input image buffer.
04 The IMAGE_BUFFER_WORD_LENGTH is zero; a length must be given for
the input image buffer.
05 An invalid value is specified for the INPUT_REQUEST_TYPE field.
7833 1733–004 20–9

SAR$ COM
Table 20–3. SAR$: COM Procedure CALL_STATUS Codes
Octal Code Status
06 An illegal character set type is specified for the
OUTPUT_CHARACTER_TYPE.
07 An illegal value is specified for the OUTPUT_TEXT_BUFFER_ADDRESS.
010 The OUTPUT_TEXT_BUFFER_BYTE_LENGTH is zero; a length must be given
for the output text buffer.
011 An illegal value is specified for INPUT_TEXT_BUFFER_ADDRESS.
012 There are no valid characters in the output image.
013 The input or output image is too long to fit in the image buffer. The image
buffer word length necessary to hold the entire image is returned in the field
RECOMMENDED_BUFFER_LENGTH.
014 The character text is too long to fit in the input text buffer and has been
truncated. The text buffer byte length necessary to hold the character text is
returned in the field RECOMMENDED_BUFFER_LENGTH.
015 The number of attributes is too large to fit in the input attribute table. The
attribute table word length necessary to hold all the attributes is returned in
the field RECOMMENDED_BUFFER_LENGTH.
016 An incorrect internal format to ACD translation routine version is being used.
017 An incorrect ACD to internal format translation routine version is being used.
020 The output attribute table contains an index that is either zero, not in
sequential order, or greater than the output text length.
021 The output attribute table contains an invalid attribute type or an invalid value
for an attribute type.
022 The image read contains incorrectly formatted ACD or incorrectly formatted
embedded shift-coded kanji.
023 The caller has illegally set a secured control bit in the CONTROL_BITS field.
024 The current Exec level does not allow ACD to be output or input with ER
COM$.
0100 An unrecognized error has occurred in an ACD subroutine. The ACD error
code is returned in the SUB_STATUS field.
0101 An unrecognized error has occurred in executing ER COM$. The COM$
error code is returned in the SUB_STATUS field.
A CALL_STATUS code of 0100 or greater is a SAR$ internal error.
20–10 7833 1733–004

20.2. SAR$ COM Function/MASM Interface
The SAR$ COM function writes a symbolic image to the operator's console and
optionally reads a symbolic image from the operator's console.
SAR$ COM
The SAR$ COM procedure is callable directly from MASM. The SAR$ data structure
definitions and procedure calls are defined by MASM procedures (PROCs). The element
SAR$PROCS contains these PROCs.
20.2.1. SAR$ COM Packet and Data Area Description
The SAR$ COM function requires a SAR$ COM packet and data area for the COM
procedure call. The S$ARCOMDEF PROC generates the EQUFs defining the COM
packet fields. The word length of the SAR$ MASM COM packet and data area is at label
SC$PKTWLEN defined by the S$ARCOMDEF PROC (the current length is 57 words).
20.2.1.1. Required Information for SAR$ COM Procedure
The calling program must set the following fields of the COM packet to appropriate
values:
SC$PKTVER
The SAR$ COM packet data structure version. The current version is equal to the
label SC$CURVER defined by the S$ARCOMDEF PROC.
SC$OTEXTB
The address of the output text buffer which contains the character text of the image
that the SAR$ COM function writes out.
SC$OTEXTBL
The length in 9-bit bytes of the character text in the text buffer. This is the number
of characters that the SAR$ COM function writes out.
SC$ITEXTB
The address of the input text buffer which contains the character text of the image
that the SAR$ COM function reads in. This field is not necessary if SC$ITEXTBL is
set to zero.
SC$ITEXTBL
The length in 9-bit bytes of the input text buffer; this is the maximum number of
characters that the SAR$ COM function will read in. If this field is set to zero, no
input is solicited from the operator's console.
7833 1733–004 20–11

SAR$ COM
20.2.1.2. Optional Information for SAR$ COM Procedure
The calling program may optionally set the following fields of the COM packet. The
default values are obtained by zero-filling the SAR$ COM packet before placing any
information in the packet.
SC$OCHART
The character set type of the image written out by the SAR$ COM function:
0 ASCII/ISO 9-bit characters (default), including all ASCII-like types in Table H–1.
1 Attributed character data (ACD).
Other character set types may not be written out by the SAR$ COM. See 18.3 for
details on the allowed output character set types.
SC$IMGBUF
The address of the image buffer; this buffer is necessary if either the output or input
character set types are ASCII/ISO with embedded shift-coded kanji or ACD. The
default is no image buffer.
SC$IMGBUFL
The length in words of the image buffer; a length must be specified if an address is
given in SC$IMGBUF. A length of zero indicates there is no image buffer (default).
SC$OATTRT
The address of the output attribute table, which contains the attributes that describe
the character text of the image that the SAR$ COM function writes out. If there are
no attributes for the output image, this table is not necessary. The default is no
output attribute table.
SC$OATTRTL
The number of valid entries in the attribute table. (Each entry is one word.) A value
of zero indicates that there is no output attribute table (default).
SC$IATTRT
The address of the input attribute table, which contains the attributes that describe
the character text of the image that the SAR$ COM function reads in. If the input
image does not have any attributes, this table is not necessary. The default is no
input attribute table.
SC$IATTRTL
The length in words of the input attribute table. A length of zero indicates that there
is no input attribute table (default).
20–12 7833 1733–004

SC$ISLIST
SAR$ COM
The address of the input select list that specifies which attributes of the input image
to return to the caller. The default is no input select list.
SC$ISLISTL
The length in 9-bit bytes of the input select list. A length of zero indicates that there
is no input select list (default).
SC$REQTYPE
The request type for the input image:
0
1
SC$CONSCLA
Do not search for embedded shift-coded kanji in input images of character set
type ASCII/ISO (default).
Search ASCII/ISO input images for any embedded shift-coded kanji, and return
the image in internal format (text part and attributes part). This request type
requires an image buffer and an input attribute table.
The console class that the ER COM$ request is directed to:
0 System console (default).
1 I/O activity console.
2 Communications console.
3 Hardware confidence console.
4, 5, 6, 7 Individual site-defined consoles for octal codes 4 to 7.
See the ER COM$ section, Exec ER Programming Reference Manual for further
details.
SC$CNTLB
The caller-supplied control bits for the ER COM$ request (default is zero). See the
ER COM$ section, Exec ER Programming Reference Manual for further details.
SC$ACNTLB
The caller-supplied additional control bits for the ER COM$ request. SAR$ COM
always sets bit 01 in addition to any caller supplied bits. See the ER COM$ section,
Exec ER Programming Reference Manual for further details.
7833 1733–004 20–13

SAR$ COM
SC$RUNIDW1
The first four ASCII characters of the run-id to use when logging the console
message. See the ER COM$ section, Exec ER Programming Reference Manual for
further details.
SC$RUNIDW2
The second four ASCII characters of the run-id.
SC$ROUTW1
Routing information on the console to which the message is to be sent. The word
may be a 6-Fieldata character-site id or may be binary information returned by
ER KEYIN$. See the ER COM$ section, Exec ER Programming Reference Manual
for further details.
SC$ROUTW2
A second word of routing information. This definition is a legacy from Exec levels
prior to 40R1 and is supplied for compatibility only. All currently supported Exec
levels use one word for routing information, the previously described SC$ROUTW1.
20.2.1.3. Information Returned by COM Procedure
The following fields of the SAR$ COM packet contain values returned by the SAR$ COM
procedure to the calling program:
SC$STATUS
The COM function status word; it contains the call status in H2 and the substatus in
S1.
SC$CALLST
The status code of the current COM procedure call. See Table 20–5 for an
explanation of the octal status codes.
SC$SUBSTAT
This field contains additional information for particular call status codes.
SC$RECBUFL
The recommended buffer or table length returned by the SAR$ COM procedure
when an invalid length is specified or when an overflow occurs.
20–14 7833 1733–004

SC$OIMGLEN
The length in bytes of the image written out by the SAR$ COM procedure.
SC$TEXTLEN
SAR$ COM
The length in 9-bit bytes of the character text read from the operator's console and
returned in the input text buffer.
SC$NUMATTR
The number of attributes returned in the input attribute table.
20.2.1.4. COM Packet Definition PROC (S$ARCOMDEF)
The MASM PROC S$ARCOMDEF generates EQUFs that define the SAR$ COM packet.
The calling program may optionally attach an X-register and a B-register to these EQUFs.
This allows the calling program to allocate storage space for the COM packet either
statically at assembly time or dynamically at execution time.
The calling program may display the EQUF labels by setting a display-flag parameter on
the PROC call. This PROC also generates EQUs defining the COM packet current
version and word length at the labels SC$CURVER and SA$PKTWLEN, respectively.
Calling Format
S$ARCOMDEF x-reg,b-reg,dispflg
Parameters
x-reg
b-reg
dispflg
The X-register that is attached to the COM packet EQUFs. If it is omitted, no
X-register is attached to the EQUFs.
The B-register that is attached to the COM packet EQUFs. If it is omitted, no
B-register is attached to the EQUFs.
A flag that displays a table of the COM packet EQUFs. If it is set to 'D', the field
names are displayed; otherwise the field names are not displayed.
7833 1733–004 20–15

SAR$ COM
Example
$ASCII
$INCLUDE ‘MAXR$’
S$ARCOMDEF X6,B3,‘D’
The PROC call S$ARCOMDEF generates EQUFs using registers X6 and B3 and displays
a description of each packet field.
20.2.1.5. SAR$ COM Packet Generation PROC (S$ARCOMPKT)
The PROC S$ARCOMPKT generates a COM packet and reserves space for an image
buffer, output text buffer, output attribute table, input text buffer, and input attribute
table. S$ARCOMPKT also calls the S$ARCOMDEF PROC, defining the COM packet
fields.
Calling Format
S$ARCOMPKT x-reg,b-reg,dispflg
The parameters for S$ARCOMPKT are the same as for the S$ARCOMDEF PROC
(see 20.2.1.4).
Returns
The S$ARCOMPKT PROC places values in the following fields of the COM packet:
SA$PKTVER SA$IMGBUF SA$IMGBUFL
SA$OTEXTBL SA$OATTRT SA$ITEXTB
SA$ITEXTB SA$ATTRT SA$IATTRTL
All other packet fields are set to default values.
The generated buffers and tables use the default lengths (see Table 20–4). The
following externalized labels are used to reference the buffers and tables:
SCIMGBUF Image buffer
SCOTEXTB Output text buffer
SCOATTRT Output attribute table
SCITEXTB Input text buffer
SCIATTRT Input attribute table
20–16 7833 1733–004

20.2.2. MASM SAR$ COM Procedure Buffers and Tables
SAR$ COM
All buffers and tables must be provided by the calling program. The buffers and tables
for the COM function are similar to the buffers and tables for the READ and WRITE
functions. See 17.1.2 and 18.1.2 for details on the buffers and tables. Note that for the
COM function, the image buffer is not used if the input and output images do not have
character attributes. The recommended lengths for the buffers and tables are equated
to labels in the S$ARCOMDEF PROC. These lengths and labels are listed in Table 20–4.
Table 20–4. SAR$: MASM COM Buffer and Table Lengths
Label Value
SC$IMGBUFDL (Image buffer word length) 25
SC$TEXBUFDL (Text buffer byte length) 80
SC$ATTRIBDL (Attribute table word length) 10
SC$SELLSTDL (Select list byte length) 4
20.2.3. SAR$ MASM COM Procedure Call (S$ARCOM)
The MASM procedure for the SAR$ COM function is S$ARCOM. The S$ARCOM PROC
constructs an image from the output text and output attributes and writes the image to
the operator's console. If input is solicited from the operator, an image is read from the
console, and the character text and attributes of the image are returned to the caller.
Initial Conditions
The calling program sets the following parameters in the COM packet to appropriate
values before calling the S$ARCOM PROC:
• Required parameters (described in 20.2.1.1)
SC$PKTVER
SC$ITEXTB
SC$OTEXTB
SC$ITEXTBL
SC$OTEXTBL
7833 1733–004 20–17

SAR$ COM
• Optional parameters (described in 20.2.1.2)
SC$OCHART
SC$OATTRT
SC$IATTRTL
SC$REQTYPE
SC$RUNIDW1
SC$ROUTW2
SC$IMGBUF
SC$OATTRTL
SC$ISLIST
SC$CONSCLA
SC$RUNIDW2
SC$IMGBUFL
SC$IATTRT
SC$ISLISTL
SC$CNTLB
SC$ACNTLB
SC$ROUTW1
Calling Format
S$ARCOM compkt
error return
normal return
Returns
If S$ARCOM takes the error return, A1 contains the call status code and A3 contains
the substatus code. These status codes are also returned in the packet fields
SC$CALLST and SC$SUBSTAT, respectively. See 20.2.4 for an explanation of the
status codes.
If S$ARCOM takes the normal return, the COM call is successful. The following
information is returned by COM to the caller:
• Character text
The address of the character text and the length in 9-bit bytes (characters) are
returned in the fields SC$ITEXTB and SC$TEXTLEN, respectively. The character
set type of the image read is the same as the output character set type.
• Attributes
The address of the attribute table and the number of entries are returned in the
fields SC$IATTRT and SC$NUMATTR, respectively.
20–18 7833 1733–004

20.2.4. Status Lists for the MASM COM Procedure
SAR$ COM
The SAR$ COM procedure call status codes listed in Table 20–5 may be returned to the
calling program in the SC$CALLST field of the COM packet. These call status codes are
for SC$CURVER = 1 and above.
Table 20–5. SAR$: COM Procedure SC$CALLST Status Codes
Octal Code Status
0 Normal return from the SAR$ COM procedure.
01 An outdated SAR$ COM packet version is being used.
02 An invalid SAR$ COM packet version is being used.
03 The value for SC$IMGBUF is zero; an address must be given for the
image buffer.
04 The value for SC$IMGBUFL is zero; a length must be given for the
image buffer.
05 An invalid value is specified for SC$REQTYPE.
06 An illegal character set type is specified for SC$OCHART.
07 An illegal address is specified for SC$OTEXTB.
010 The value for SC$OTEXTBL is zero; a length must be given for the
output text buffer.
011 An illegal address is specified for SC$ITEXTB.
012 There are no valid characters in the output image.
013 The input or output image is too long to fit in the image buffer. The
image buffer word length necessary to hold the entire image is
returned in the field SC$RECBUFL.
014 The character text is too long to fit in the input text buffer and has
been truncated. The text buffer byte length necessary to hold the
character text is returned in the field SC$RECBUFL.
015 The number of attributes is too large to fit in the input attribute
table. The attribute table word length necessary to hold all the
attributes is returned in the field SC$RECBUFL.
016 An incorrect internal format to ACD translation routine version is
being used.
017 An incorrect ACD to internal format translation routine version is
being used.
020 The output attribute table contains an index that is either zero, not
in sequential order, or greater than the output text length.
021 The output attribute table contains an invalid attribute type or an
invalid value for an attribute type.
022 The image read contains incorrectly formatted ACD or incorrectly
formatted embedded shift-coded kanji.
7833 1733–004 20–19

SAR$ COM
Table 20–5. SAR$: COM Procedure SC$CALLST Status Codes
Octal Code Status
023 The caller has illegally set a secured control bit in the SC$CNTLB
field.
024 The current Exec level does not allow ACD to be output or input
with ER COM$.
0100 An unrecognized error has occurred in an ACD subroutine. The
ACD error code is returned in the SC$SUBSTAT field.
0101 An unrecognized error has occurred in executing ER COM$. The
COM$ error code is returned in the SC$SUBSTAT field.
A SC$CALLST status code of 0100 or greater is a SAR$ internal error.
20–20 7833 1733–004

Section 21
SDFI, SDFO–System Data Format I/O
Routines
The System Data Format Input (SDFI) routine and the System Data Format Output
(SDFO) routine are two independent routines that process files or elements that are in
system data format (SDF).
The SDFI routine reads SDF images from the input file or element and returns the
images one at a time to the calling program. The SDFO routine takes SDF images one at
a time from the calling program and writes the images to the output file or element.
The SDFI and SDFO routines each require the following data structures:
• A packet or file control table (FCT)
• An image buffer
• One or two I/O buffers
An 11-word packet is used to pass information to and from SDFI and SDFO. The packet
format for SDFI is described in 21.1.1. The packet format for SDFO is described in
21.2.1.
The image buffer is either the data area that SDFI reads the next image into or the data
area containing the image that SDFO writes out.
The I/O buffers are used by SDFI and SDFO to access the file or element. The I/O buffer
length must be a multiple of 28 words (one sector). If there are two I/O buffers, they
must be of equal length. Because the physical record size on disks is most frequently
four sectors (112 words), SDFI and SDFO execute most efficiently when their buffer
lengths are a multiple of 112 words. If the buffer length is larger than but not a multiple
of 112 words, the excess length (28, 56, or 84 words) is not used in I/O operations
unless the I/O device is a tape drive.
If the file accessed by SDFI or SDFO is on tape, the buffer length should be the length of
the tape block. The standard tape block length is 224 words. SDFI and SDFO can
handle multireel tape files correctly. SDFI and SDFO send a message to the print device
each time an input or output tape reel is swapped.
SDFI and SDFO assume that the file being accessed is assigned to the run before SDFI
and SDFO are called.
7833 1733–004 21–1

SDFI, SDFO–System Data Format I/O Routines
The SDFI and SDFO routines are available as relocatable elements and also in the
SYSLIB common banks. SDFI is in the common bank absolute SYSLIB$3, and SDFO is
in the common bank absolute SYSLIB$4. Both routines are reentrant. The relocatable
and common bank entry points for SDFI and SDFO are listed in Appendix E.
The following compatibility considerations apply to FURPUR and Processor Common
Input/Output System (PCIOS):
• SDFI and SDFO are fully compatible with FURPUR level 28R3 and higher levels.
• SDFI and SDFO are compatible with PCIOS levels 4R1 and 4R1A, except for the
handling of multireel tape files:
− When SDFI reads multireel tape files created by PCIOS, I/O error 01 (unlabeled
tape) or TLBL$ error 013 (labeled tape) occurs.
− When PCIOS reads multireel tape files created by SDFO, unlabeled tapes are
read correctly, but labeled tapes encounter I/O error 01.
• SDFI returns segmented PCIOS records one segment at a time. The caller must
examine the segment flag in the PCIOS data record control word to determine how
the data record is segmented.
A description of each routine and its corresponding packet is in the following
subsections.
For details on system data format, see the Data Structures Programming Reference
Manual.
21.1. SDFI–System Data Format Input Routine
The SDFI routine returns one SDF image at a time from an SDF file or element. SDFI
has the following functions and entry points:
• Open SDFI (SDFIO$, SDFIOA$)
• Read an image (SDFI$, SDFINT$)
• Close SDFI (SDFIC$)
The calling program must open SDFI before reading images from the file or element and
close SDFI after all images are read.
The packet (or FCT) for SDFI is described in 21.1.1. The open, read, and close functions
of SDFI are described in 21.1.2.1, 21.1.2.2, and 21.1.2.3, respectively.
21.1.1. Packet
The calling program must provide an 11-word packet for SDFI. The SDFI packet format
is described in Figure 21–1. The packet may be generated with the S$DFCT procedure
described in 21.1.1.2.
21–2 7833 1733–004

SDFI, SDFO–System Data Format I/O Routines
The same 11-word packet should not be used for both SDFI and SDFO.
21.1.1.1. Packet Format
The calling program must provide the eleven-word packet and place appropriate
information in all fields with names in italics.
0 internal filename
1
2 zero
3 zero 020 reserved zero
4 buffer length (words) single buffer address
5 Relative Mass Storage Address (Sector)
6 address of buffer number 1 address of buffer number 2
7 buffer length (sectors) length of image area
8 zero (used by SDFI) image area location
9 zero (used by SDFI) image location in buffer (filled)
10 SDF Control Word (filled)
Packet Fields
Words 0,1
Figure 21–1. SDFI: Packet Format
The 12-character Fieldata internal file name.
Word 3 (S2)
The I/O read function, R$ or 020.
Word 4 (H1)
The length in words of the I/O buffer used by SDFI.
Word 4 (H2)
The address of the I/O buffer if using one buffer.
Word 5
The mass storage sector address of the first SDF image to be read.
7833 1733–004 21–3

SDFI, SDFO–System Data Format I/O Routines
Word 6
The addresses of the I/O buffers when two buffers are used. If only one buffer is
used, this word must be zero, and the address of the single buffer must be put in
word 4.
Word 7 (H1)
The length in sectors of the I/O buffers used by SDFI.
Word 7 (H2)
The length in words of the image buffer into which SDFI transfers the individual SDF
images.
Word 8 (H2)
The address of the image buffer into which SDFI transfers the individual images.
Word 9 (H2)
The location in the I/O buffer of the next SDF image to be read (filled by SDFI).
Word 10
The SDF control word of the image read (filled by SDFI).
SDFI may use one or two buffers. If SDFI uses one I/O buffer, that buffer address is
stored in H2 of word 4. Word 6 must be set to zero. If SDFI uses two I/O buffers, the
buffer addresses are placed in H1 and H2 of word 6. Words 0 through 5 are the
standard I/O packet used by Executive Requests.
21.1.1.2. Packet Generation PROC
S$DFCT is a MASM procedure that generates the SDFI packet (or FCT). S$DFCT
defines the fields of the packet, initializes the packet, and displays a diagram of the
packet.
The MASM definition element SDFP$ contains the S$DFCT procedure. This element
must be included in the calling program in order to use the S$DFCT procedure. It is
included by using the following MASM directive:
$INCLUDE ‘SDFP$’
21–4 7833 1733–004

SDFI, SDFO–System Data Format I/O Routines
S$DFCT Calling Sequence
There are two calling sequences for the S$DFCT procedure. The first call is used if the
G-option is specified. The second call is used if the G-option is not specified.
• Call 1 (G-option specified)
label S$DFCT,o ifn,f,msa blw,buf1,buf2;
ialng,ialoc w,x,l
This call generates the packet definitions, initializes the packet, and displays the
packet in the calling programs assembly.
• Call 2 (G-option not specified)
label S$DFCT,o w,x,l
This call generates the packet definitions and displays the packet, but it does not
initialize the packet.
Parameters
label
o
Prefix for field names (see L-option)
Options (in quotes)
D
G
L
N
S
Display the packet diagram, including user-defined names.
Generate packet from parameters on Call 1.
Generate dynamic definitions using label on S$DFCT call as prefix for field
names.
Suppress listing of data while generating packet.
Use standard field names (FCTxxxx) with or without word offset and index
register.
The S option is the default if neither the S nor L option is present. The L option
overrides the S option if both the S and L options are present.
7833 1733–004 21–5

SDFI, SDFO–System Data Format I/O Routines
ifn
f
msa
blw
buf1
buf2
ialng
ialoc
w
x
l
Internal file name (in quotes)
I/O function code: R$ - Read (020)
Mass storage address
Buffer length in words
Buffer address 1
Buffer address 2 (optional). If not specified, the packet is generated for 1 buffer.
Image area length
Image area location
Address on which to base definitions (word offset). If omitted, the current location is
used.
Index register for dynamic definitions
Levels above calling point to which definitions are known.
If omitted, main assembly is used. If specified, one level above the main assembly
is the maximum allowed; otherwise the main assembly level is the maximum.
If buf2 is not specified, S$DFCT generates the FCT using single buffering.
21–6 7833 1733–004

SDFI, SDFO–System Data Format I/O Routines
Example
The following example generates the packet (FCT) for SDFI with the S$DFCT PROC:
1. $ASCII
2. $INCLUDE ‘MAXR$’
3. $INCLUDE ‘SDFP$’
4. $(2)
5. PKT S$DFCT,‘DGL’ ‘TPF$’,R$,1792 448,BUF1,BUF2;
6. 20,LINE ,X7
7. BUF1 $RES 448
8. BUF2 $RES 448
9. LINE $RES 20
.
.
.
10. $(1)
11. START
12. L,U X7,PKT . Get address of packet
.
.
.
13. L A6,PKTICW . Get Image Control Word
In this example, the packet (FCT) for SDFI is generated on line 5 by the S$DFCT PROC.
The D option displays the packet in the MASM assembly. The G option initializes the
packet with the information contained in the S$DFCT parameter fields 1, 2, and 3. The
L option generates dynamic $EQUF definitions using the label field on the S$DFCT
PROC and information in parameter field 4. In this case, the $EQUF labels are prefixed
with 'PKT', use X-register X7, and are externalized to the main assembly level.
Line 13 accesses word 10 of the SDFI packet using the $EQUF generated by the
S$DFCT PROC.
21.1.2. Calling Sequence
The following subsections explain how to open the SDFI routine, read an image, and
close the routine.
21.1.2.1. Open SDFI
The calling program must open SDFI before any images can be read. There are two
entry points that perform the open function.
SDFIO$ Open SDFI at sector address
SDFIOA$ Open SDFI at sector address and word offset
When the SDFIO$ entry point is called, SDFI fills the I/O buffer or buffers and tests if the
file accessed is an SDF file. Reading begins at the sector address specified in word 5 of
the packet.
7833 1733–004 21–7

SDFI, SDFO–System Data Format I/O Routines
The SDFIOA$ entry point is the same as SDFIO$ except that the calling program can
specify a word offset into the initial read sector address. This allows SDFI to begin
reading on a word boundary instead of a sector boundary. The word offset must be in
the range of 0 through 27. If the word offset is 0, SDFIOA$ performs the same as
SDFIO$.
Calling Sequence for SDFIO$
Auto Switch Common Bank or Relocatable Relocatable
L,U A0,address-of-packet
LMJ X11,CBSDFIO$-1
error return
normal return
Calling Sequence for SDFIOA$
L,U A0,address-of-packet
I$BJ X11,CBSDFIO$
error return
normal return
L,U A0,address-of-packet
LMJ X11,SDFIO$
error return
normal return
Auto Switch Common Bank or Relocatable Relocatable
L,U A0,address-of-packet
L A1,word-offset
LMJ X11,CBSDFIOA$-1
error return
normal return
L,U A0,address-of-packet
L A1,word-offset
I$BJ X11,CBSDFIOA$
error return
normal return
L,U A0,address-of-packet
L A1,word-offset
LMJ X11,SDFIOA$
error return
normal return
If SDFI takes the error return, register A4 contains the error code. See 21.3 for an
explanation of error codes.
If SDFI takes the normal return, SDFI is opened and ready to read images.
21.1.2.2. Read an Image
Each call to SDFI$ or SDFINT$ reads one image from the file or element. SDFI returns
the image in the image buffer and returns the image control word (ICW) in word 10 of
the packet. There are two entry points to read an image.
SDFI$ read an image (truncation if image overflows image buffer)
SDFINT$ read an image (no truncation)
The only difference between SDFI$ and SDFINT$ is how they handle an image buffer
overflow. The SDFI$ entry point truncates images that are too long to fit in the image
buffer. The image buffer is filled, and the rest of the image is lost. SDFI returns the total
length of the image in word 10 (T1) of the FCT if the image is truncated. Therefore, the
caller may detect if an image was truncated by checking whether the image length
returned in word 10 (T1) of the FCT is greater than the image buffer length.
21–8 7833 1733–004

SDFI, SDFO–System Data Format I/O Routines
The SDFINT$ entry point does not truncate images that overflow the image buffer but
instead returns an error. The recommended image buffer word length is returned in
register A5. To read the entire image, the calling program must place the address and
word length of a larger image buffer in the packet and call SDFINT$ again. If a
continuation record (051 in S1 of the ICW) causes an overflow, the image buffer will
contain the part just read, and word 10 of the FCT will contain an ICW for the portion of
the image returned in the image buffer. To continue reading the image, the calling
program must call SDFINT$ again. SDFI will return the next portion of the image.
SDFI processes continuation records (051 in S1 of the ICW) and does not return them to
the calling program, unless the image being continued is a type 061 special print control
record. Since the type 061 record may exceed 63 words in length, the special print
control record will be returned, and each continuation record associated with that special
print control record will be returned as a separate record. All other control records are
returned to the calling program.
Calling Sequence for SDFI$
Auto Switch Common Bank or Relocatable Relocatable
L,U A0,address-of-packet
LMJ X11,CBSDFI$-1
error return
end-of-file return
normal return
Calling Sequence for SDFINT$
L,U A0,address-of-packet
I$BJ X11,CBSDFI$
error return
end-of-file return
normal return
L,U A0,address-of-packet
LMJ X11,SDFI$
error return
end-of-file return
normal return
Auto Switch Common Bank or Relocatable Relocatable
L,U A0,address-of-packet
LMJ X11,CBSDFINT$-1
error return
end-of-file return
normal return
L,U A0,address-of-packet
I$BJ X11,CBSDFINT$
error return
end-of-file return
normal return
L,U A0,address-of-packet
LMJ X11,SDFINT$
error return
end-of-file return
normal return
Returns
If SDFI takes the error return, register A4 contains the error code. See 21.3 for an
explanation of error codes.
If SDFI takes the end-of-file return, an end-of-file control record was encountered (077 in
S1 of the ICW). If the file or element read by SDFI does not contain an EOF control
record, SDFI does not terminate correctly.
If SDFI takes the normal return, the image has been read and is returned in the image
buffer.
7833 1733–004 21–9

SDFI, SDFO–System Data Format I/O Routines
21.1.2.3. Close SDFI
After all the images are read, the calling program must close SDFI by calling the SDFIC$
entry point. This completes the SDFI read operation.
Calling Sequence for SDFIC$
Auto Switch Common Bank or Relocatable Relocatable
L,U A0,address-of-packet
LMJ X11,CBSDFIC$-1
normal return
L,U A0,address-of-packet
I$BJ X11,CBSDFIC$
normal return
L,U A0,address-of-packet
LMJ X11,SDFIC$
normal return
21.2. SDFO–System Data Format Output Routine
SDFO writes images one at a time from the calling program to an SDF file or element.
SDFO has the following functions and entry points:
• Open SDFO (SDFOO$, SDFOOSF$)
• Write an image (SDFO$)
• Close SDFO (SDFOC$)
The calling program must open SDFO before writing images to the file or element and
close SDFO after all images are written.
The packet (or FCT) for SDFO is described in 21.2.1. The open, write, and close
functions of SDFO are described in 21.2.2.1, 21.2.2.2, and 21.2.2.3, respectively.
21.2.1. Packet
The calling program must provide an 11-word packet for SDFO. The packet (or FCT) for
SDFO is described in Figure 21–2. The packet may be generated with the S$DFCT
procedure, described in 21.2.1.2.
The same 11-word packet should not be used for both SDFI and SDFO.
21–10 7833 1733–004

21.2.1.1. Packet Format
SDFI, SDFO–System Data Format I/O Routines
The calling program must provide the 11-word packet and place appropriate information
in all fields with names in italics.
0 internal filename
1
2 zero
3 zero 010 reserved zero
4 buffer length in words (filled) single buffer address
5 Relative Mass Storage Address (Sector)
6 address of buffer number 1 address of buffer number 2
7 buffer length (sectors) length of image area (filled)
8 zero image area location
9 zero buffer image locator (filled)
10 SDF Control Word
Packet Fields
Words 0,1
Figure 21–2. SDFO: Packet Format
The 12-character Fieldata internal file name.
Word 3 (S2)
The I/O write function, W$ or 010.
Word 4 (H1)
The length in words of the I/O buffer or buffers used by SDFO (filled by SDFO).
Word 4 (H2)
The address of the I/O buffer if using one buffer; otherwise zero.
Word 5
The mass storage sector address to start writing SDF images to.
Word 6
The addresses of the I/O buffers if using two buffers (in H1 and H2); otherwise zero.
7833 1733–004 21–11

SDFI, SDFO–System Data Format I/O Routines
Word 7 (H1)
The length in sectors of the I/O buffer used by SDFO.
Word 7 (H2)
The length in words of the SDF image transferred from the image buffer (filled by
SDFO).
Word 8 (H2)
The address of the image buffer containing the SDF image that SDFO writes out.
Word 9 (H2)
The location in the buffer that SDFO places the next image to be written out (filled
by SDFO).
Word 10
The SDF control word of the image that SDFO writes out.
SDFO may use one or two buffers. If SDFO uses one output buffer, that buffer address
is stored in H2 of word 4. Word 6 must be set to zero.
If SDFO uses two buffers, the buffer addresses are placed in H1 and H2 of word 6. H2
of word 4 must be set to zero.
SDF Image Control Word Formats
The calling program must place an ICW in word 10 for each SDF data record or control
record written out.
SDFO does not automatically generate 051 continuation control records. These are
generally found only in symbiont generated print files.
The general format of the ICW for an SDF data record is as follows:
image length (words) variable information
0 1 11 12 35
The general format of the ICW for an SDF control record is as follows:
control code image length variable information
0 5 6 11 12 35
The ICW for SDF control records always has bit 0 set.
SDF is described in the Data Structures Programming Reference Manual.
21–12 7833 1733–004

21.2.1.2. Packet Generation PROC
SDFI, SDFO–System Data Format I/O Routines
S$DFCT is a MASM procedure that generates the SDFO packet (or FCT). S$DFCT
defines the fields of the packet, initializes the packet, and displays a diagram of the
packet.
The MASM definition element SDFP$ contains the S$DFCT procedure. This element
must be included in the calling program in order to use the S$DFCT procedure by using
the following MASM directive:
$INCLUDE ‘SDFP$’
S$DFCT Calling Sequence
There are two calling sequences for the S$DFCT procedure. The first call is used if the
G-option is specified. The second call is used if the G-option is not specified.
• Call 1 (G-option specified)
label S$DFCT,o ifn,f,msa blw,buf1,buf2;
ialng,ialoc,icw w,x,l
• Call 2 (G-option not specified)
label S$DFCT,o w,x,l
The first call generates the packet definitions, initializes the packet, and displays the
packet in the calling program's assembly. The second call generates the packet
definitions and displays the packet but does not initialize the packet.
Parameters
label
o
Prefix for field names (see L-option)
Options (must be in quotes)
D
G
L
Display the packet diagram, including user-defined names.
Generate packet from parameters on Call 1.
Generate dynamic definitions using label on S$DFCT call as prefix for field
names.
7833 1733–004 21–13

SDFI, SDFO–System Data Format I/O Routines
ifn
f
msa
blw
buf1
buf2
ialng
ialoc
icw
N
S
Suppress listing of data while generating packet.
Use standard field names (FCTxxxx) with or without word offset and index
register.
The S option is the default if neither the S nor L option is present. The L option
overrides the S option if both the S and L options are present.
Internal file name (in quotes)
I/O function code:
W$–Write (010)
Mass storage address
Buffer length in words
Buffer address 1
Buffer address 2 (optional). If not specified, the packet is generated for 1 buffer.
Image area length
Image area location
Image control word
21–14 7833 1733–004

w
x
l
SDFI, SDFO–System Data Format I/O Routines
Address on which to base definitions (word offset). If omitted, the current location is
used.
Index register for dynamic definitions
Levels above calling point to which definitions are to be known.
If omitted, main assembly is used. If specified, one level above the main assembly
is the maximum allowed; otherwise the main assembly level is the maximum.
If buf2 is not specified, S$DFCT generates the FCT using single buffering.
Example
The following example generates the packet (FCT) for SDFO with the S$DFCT PROC:
1. $ASCII
2. $INCLUDE ‘MAXR$’
3. $INCLUDE ‘SDFP$’
4. $(2)
5. PKT S$DFCT,‘DGL’ ‘TPF$’,W$,1792 448,BUF1,BUF2;
6. 20,LINE ,X7
7. BUF1 $RES 448
8. BUF2 $RES 448
9. LINE $RES 20
.
.
.
10. $(1)
11. START
12. L,U X7,PKT . Get address of packet
13. L A6,(0500130000001)
14. S A6,PKTICW . Store label ICW
.
.
.
In this example, the packet (FCT) for SDFO is generated on line 5 by the S$DFCT PROC.
The D option displays the packet in the MASM assembly. The G option initializes the
packet with the information contained in the S$DFCT parameter fields 1, 2, and 3. The L
option generates dynamic $EQUF definitions using the label field on the S$DFCT PROC
and information in parameter field 4. In this case, the $EQUF labels are prefixed with
'PKT', use X-register X7, and are externalized to the main assembly level.
Line 13 and 14 store a label control record in the SDFO packet using the $EQUF
generated by the S$DFCT PROC.
7833 1733–004 21–15

SDFI, SDFO–System Data Format I/O Routines
21.2.2. Calling Sequence
The following subsections explain how to open the System Data Format Output routine,
read an image, and close it.
21.2.2.1. Open SDFO
The calling program must open SDFO before any images can be written. There are two
entry points that perform the open function.
SDFOO$ Open SDFO for any file type
SDFOOSF$ Open SDFO for a sector-formatted file
When the SDFOO$ entry point is called, SDFO initializes the packet for writing to the file
or element. If the output file type is known to be sector-formatted, the SDFOOSF$ entry
point should be used. This entry point is the same as SDFOO$ except that SDFO does
not need to perform an ER FITEM$.
Calling Sequence for SDFOO$
Auto Switch Common Bank or Relocatable Relocatable
L,U A0,address-of-packet
LMJ X11,CBSDFOO$-1
normal return
Calling Sequence for SDFOOSF$
L,U A0,address-of-packet
I$BJ X11,CBSDFOO$
normal return
L,U A0,address-of-packet
LMJ X11,SDFOO$
normal return
Auto Switch Common Bank or Relocatable Relocatable
L,U A0,address-of-packet
LMJ X11,CBSDFOOSF$-1
normal return
L,U A0,address-of-packet
I$BJ X11,CBSDFOOSF$
normal return
L,U A0,address-of-packet
LMJ X11,SDFOOSF$
normal return
21–16 7833 1733–004

21.2.2.2. Write an Image
SDFI, SDFO–System Data Format I/O Routines
Each call to SDFO$ writes one image to the file or element. The calling program must
supply the image and an ICW for the image. The calling program places the image in the
image buffer and places the ICW in word 10 of the SDFO packet. SDFO combines the
ICW and the image and places them in the I/O buffer to be written out.
SDFO does not actually write an image to the file or element every time SDFO$ is called.
SDFO places the images in the I/O buffer or buffers. When the buffer is filled or a call is
made to SDFOC$ to close SDFO, the buffer is written out to the file or element.
SDFO maintains the write address when writing to a file or element. The calling
program only needs to specify the initial write address.
Calling Sequence for SDFO$
Auto Switch Common Bank or
Relocatable
L,U A0,address-of-packet
LMJ X11,CBSDFO$-1
error return
normal return
L,U A0,address-of-packet
I$BJ X11,CBSDFO$
error return
normal return
Relocatable
L,U A0,address-of-packet
LMJ X11,SDFO$
error return
normal return
If SDFO takes the error return, register A4 contains the error code. See 21.3 for an
explanation of error codes.
If SDFO takes the normal return, the image has been successfully written to the file or
element.
21.2.2.3. Close SDFO
After all images have been written, the calling program must close SDFO by calling the
entry point SDFOC$. SDFO places an end-of-file control record (077 in S1 of the ICW) in
the I/O buffer and writes the buffer out to the file or element. If SDFO is writing to mass
storage, it returns a sector address in word 5. This is the next available address to write
to in the file. If SDFO is writing to tape, an end-of-file mark is written to the tape.
Calling Sequence for SDFOC$
Auto Switch Common Bank or
Relocatable
L,U A0,address-of-packet
LMJ X11,CBSDFOC$-1
error return
normal return
L,U A0,address-of-packet
I$BJ X11,CBSDFOC$
error return
normal return
Relocatable
L,U A0,address-of-packet
LMJ X11,SDFOC$
error return
normal return
7833 1733–004 21–17

SDFI, SDFO–System Data Format I/O Routines
21.3. Error Return
When SDFI or SDFO takes the error return, register A4 contains an error code. For
some error codes, register A5 contains additional information. The error codes are as
follows:
00
01
04
05
06
07
Unrecoverable I/O error; A5 contains the status code (see the Exec ER Programming
Reference Manual).
Error on ER TLBL$ tape label call; A5 contains the status code (see the Exec ER
Programming Reference Manual).
(SDFI entry point SDFINT$ only) The record that is read is larger than the image
buffer; the record has been truncated. The recommended image buffer word length
is returned in A5. Place the length and address of a larger image buffer in the packet
and call SDFI$ again to read the entire image.
(SDFI entry point SDFINT$ only) A continuation control record (051) made the total
record length exceed the image buffer length; the record has been truncated. The
recommended image buffer word length is returned in A5, and the word length of
the partial image transferred is in S2 of word 10 for control records, and T1 of word
10 for data records. Another call to SDFI$ will continue reading the image.
(SDFI entry points SDFI$ and SDFINT$) A continuation control record (051) made the
total record length exceed the maximum allowed word length (63 for control records,
2047 for data records).
(SDFO entry point SDFOC$ only) The code for the equipment type is zero. Either
SDFO has not been opened correctly or the SDFO packet has been corrupted.
21–18 7833 1733–004

Section 22
SFDT$–System Standard Format Date
and Time
The System Standard Format Date and Time (SFDT$) editing routine provides the calling
program with standard formats for dates and times. SFDT$ converts the current date
and time (or a specified date and time) into a string of ASCII characters. This string is
placed into a buffer provided by the calling program.
SFDT$ can create separate date and time formats or combine them together. The date
format can contain the century, year of century, month, day, abbreviation for month, and
abbreviation for day. The time format can contain the hour, minute, second, and
fractional second. The calling program determines the exact contents of the date and
time formats by selecting a date index and a time index.
There are eight standard date formats and three standard time formats to choose from.
• Date Formats
1. YYMMDD
2. CCYYMMDD
3. YY-MM-DD
4. CCYY-MM-DD
5. YY mmm DD
6. CCYY mmm DD
7. YY mmm DD ddd
8. CCYY mmm DD ddd
• Time Formats
1. HHMM
2. HHMM:SS
3. HHMM:SS.FFF
7833 1733–004 22–1

SFDT$–System Standard Format Date and Time
where:
CC
YY
MM
DD
mmm
ddd
HH
MM
SS
FFF
Two-digit decimal century
Two-digit decimal year of century
Two-digit decimal month
Two-digit decimal day of month
Three-ASCII-character abbreviation for month (see SYSLIB element SFDTBL$)
Three-ASCII-character abbreviation for day of week (see SYSLIB element SFDTBL$)
Two-digit decimal hour
Two-digit decimal minute
Two-digit decimal second
Three-digit decimal fractional second (only significant digits included)
The calling program can use the date and time formats individually or combine them.
If they are combined, the date format precedes the time format, and the formats are
separated by either a space character (" ") or a dash character ("-"). The space character
separator may be used with all formats. The dash character separator may only be used
with date formats 1 through 4.
22–2 7833 1733–004

SFDT$–System Standard Format Date and Time
Recommended Date and Time Formats
Since there are many possible date and time format combinations, the following formats
are recommended as standard:
YYMMDD HHMM:SS format (1,2) –most compact
CCYY-MM-DD HHMM:SS format (4,2)
CCYY mmm ddd HHMM:SS format (8,2) –most descriptive
The element SFDTBL$ contains the ASCII character abbreviations for months and days.
It is accessed by external label SFDTBL$. These abbreviations may be changed to other
abbreviations for months and days, for example, when using languages other than
English.
SFDT$ can be called from both MASM and PLUS routines. It is available as a relocatable
element in the SYSLIB file (SYS$LIB$*SYSLIB) or SYS$*RLIB$ and in the SYSLIB
common bank SYSLIB$1. The relocatable and common bank entry points to SFDT$ are
listed in Appendix E.
22.1. MASM Interface
SFDT$ can be called directly from MASM programs. The packet for SFDT$ is described
in 22.1.1. The calling sequence for SFDT$ is described in 22.1.2.
22.1.1. Packet
The calling program must provide a five-word packet for SFDT$. The following MASM
PROC generates this packet:
label S$FDTPKT datefmt,timefmt,buflen,bufaddr[,sep][,offset]
The packet is shown in Figure 22–1.
0 tscell datefmt timefmt sep reserved version
01 offset numchar buflen errcode
02 bufaddr
03 date
04 time
Figure 22–1. SFDT$: Packet Format
7833 1733–004 22–3

SFDT$–System Standard Format Date and Time
Packet Fields
The calling program provides the fields in italics.
tscell
datefmt
Available to the calling program as a test-and-set flag (optional).
The date format index (0 through 8) (required). It corresponds to the date formats
listed at the beginning of this section. If set to zero, no date format is used; only the
time is formatted.
timefmt
sep
The time format index (0 through 3) (required). If set to zero, no time format is used;
only the date is formatted.
A flag for which separator character to use (optional)
0 Space (" ") character (default)
1 Dash ("-") character
version
offset
The packet version number; the current version is 1 (required).
The character offset within the first word (0, 1, 2, or 3) of the SFDT$ output
(optional). If omitted, it defaults to zero. SFDT$ also returns the position of the last
nonspace character (0, 1, 2, or 3) in this field.
numchar
buflen
errcode
bufaddr
The number of characters that SFDT$ writes to the output buffer.
The length in words of buffer specified by bufaddr (required).
A negative error code returned by SFDT$ when the error return is taken.
The address of SFDT$ output buffer (required).
22–4 7833 1733–004

date
time
SFDT$–System Standard Format Date and Time
The date and time in TDATE$ format (optional). The default is the current date and
time.
The time in TIME$ format (optional). The default is the current time.
Parameters datefmt, timefmt, buflen, and bufaddr are required; sep is optional and is set
to zero (space separator) if omitted; offset is optional and is set to zero if omitted.
Output Buffer
The SFDT$ packet and the buffer to contain the ASCII string must be in the same
D-bank. This D-bank must be based when SFDT$ is called.
The caller-provided buffer must be large enough to hold the ASCII string generated by
the specified format. If not, the ASCII string is truncated to the length of the buffer
(buflen), and the error return is taken. If the buffer length is greater than the format
length, the buffer is space-filled to the end of the buffer.
22.1.2. Calling Sequence
SFDT$ is called with the MASM PROC S$FDT$. This PROC can call SFDT$ as a
relocatable element, a common bank element, or a common bank element using the
auto-switch method.
Calling Format
S$FDT$[,t] pktaddr [date] [time]
error return
normal return
Parameters
t
The type of call to SFDT$. This parameter is optional and may be omitted. CB or A,
if specified, must be enclosed by apostrophes.
blank Call the relocatable version of SFDT$. This is the default if t is omitted.
'CB' Call the common bank version of SFDT$.
'A' Call the common bank version of SFDT$ using the auto switch method.
pktaddr
The address of the five-word SFDT$ packet.
7833 1733–004 22–5

SFDT$–System Standard Format Date and Time
date
time
The address of a caller-specified date and time (must be in TDATE$ format). This
parameter is optional.
The address of a caller-specified time (must be in TIME$ format). This parameter is
optional.
If date or time are not included on the calling statement, the current date and time (from
ER TDATE$, or current time from ER TIME$ for time format 3) is used. The calling
program can use indexing, incrementation, and indirect addressing in specifying the
addresses for pktaddr, date, or time, by using the $EQUF directive. See $EQUF
definitions in the MASM Programming Reference Manual.
Returns
If the normal return is taken, SFDT$ has stored the ASCII date/time string in the buffer.
The following information is returned to the caller in registers A0 to A3 and also stored in
the packet at the appropriate locations:
A0 The address of the SFDT$ packet
A1 The number of characters in the formatted ASCII string
A2 The address of the buffer containing the ASCII string
A3 The character offset of the last nonspace character
If the error return is taken, register A0 contains the packet address, and register A1
contains the negative error code (also stored in the packet field errcode).
1 The buffer length is too short for specified format(s).
2 The date format index is out of range.
3 The time format index is out of range.
4 Both date and time formats are zero.
5 An outdated version of the SFDT$ packet is being used.
22–6 7833 1733–004

22.1.3. Example
SFDT$–System Standard Format Date and Time
The following example generates the packet for SFDT$ and calls SFDT$ from a MASM
routine:
1. $(0)
2. PACKET S$FDTPKT 8,2,LINELEN,LINE
3. LINELEN $EQU 7
4. LINE $RES LINELEN
.
.
.
5. $(1)
6. START
.
.
.
7. S$FDT$,‘CB’ PACKET . Format the date and time
In this example, lines 2 through 4 generate the packet for SFDT$. Date format 8 and
time format 2 are used, and the date/time string will be placed in the seven-word buffer
LINE. The separator character and the offset default to a space and zero, respectively.
Line 7 calls the common bank version of SFDT$ to format an ASCII string of the current
date and time.
7833 1733–004 22–7

SFDT$–System Standard Format Date and Time
22.2. PLUS Interface
SFDT$ can be called directly from PLUS programs. The packet for SFDT$ is described in
22.2.1. The calling sequence for SFDT$ is described in 22.2.2.
22.2.1. Packet
Required Data Structures
SFDT$ requires a five-word packet and a seven-word (or less) buffer area. The packet
passes parameters to SFDT$ and the buffer area contains the ASCII date/time string
generated by SFDT$. These data structures are defined as follows:
DEFINE TYPE SFDT_BUFFER = 28 ASCII CHARACTERS LOCATABLE;
DEFINE TYPE SFDT_PACKET = MAPPED LOCATABLE
[*: LOGICAL(6),
SFDT_DATE_FORMAT: 6 BIT INTEGER,
SFDT_TIME_FORMAT: 6 BIT INTEGER,
SFDT_SEPARATOR: 6 BIT STATUS (S’SPACE’:0, S’DASH’:1),
*: LOGICAL(6),
SFDT_PACKET_VERSION: 6 BIT INTEGER,
SFDT_CHAR_OFFSET: 6 BIT INTEGER,
SFDT_BUFFER_LENGTH: 6 BIT INTEGER,
SFDT_NUMBER_CHAR: 6 BIT INTEGER,
SFDT_ERROR_CODE: 18 BIT SIGNED INTEGER,
SFDT_BUFFER_ADDRESS: 36 BIT MACHINE POINTER,
SFDT_DATE: 36 BIT MACHINE LOGICAL,
SFDT_TIME: 36 BIT MACHINE LOGICAL];
The calling program can use these data types to set up the necessary data entities for
SFDT$. For example
DECLARE buffer: SFDT_BUFFER;
DECLARE pkt: SFDT_PACKET;
where:
buffer
pkt
An identifier of a buffer that SFDT$ places the ASCII date/time string into.
An identifier of a data entity that passes information to SFDT$.
The type definitions for SFDT_BUFFER and SFDT_PACKET are available in PLUS COPY
elements (see 22.2.2).
22–8 7833 1733–004

SFDT$–System Standard Format Date and Time
Parameters
The calling program must set the following variables before calling SFDT$:
SFDT_DATE_FORMAT
Specifies date format (0 through 8). If set to zero, no date format is used; only the
time is formatted.
SFDT_TIME_FORMAT
Specifies time format (0 through 3). If set to zero, no time format is used; only the
date is formatted.
SFDT_SEPARATOR
Specifies space separator (" ") between formats if set to S'Space', and dash
separator ("-") if set to S'Dash'.
SFDT_PACKET_VERSION
Specifies the SFDT$ packet version (the current version is 1).
SFDT_CHAR_OFFSET
The character offset (0, 1, 2, or 3) in the first word at which to start the ASCII
date/time string.
SFDT_BUFFER_LENGTH
Specifies the length in words of the buffer into which the string is placed.
SFDT_BUFFER_ADDRESS
Specifies a pointer to the buffer into which the string is placed.
SFDT_DATE
Value for date; may be assigned a negative integer to use current date or assigned a
positive integer or octal string value if a date other than the current date is desired
(must be in TDATE$ format).
SFDT_TIME
Value for time; may be assigned a negative integer to use current time or assigned a
positive integer or octal string value if a time other than the current time is desired
(must be in TIME$ format).
7833 1733–004 22–9

SFDT$–System Standard Format Date and Time
Initialization Procedure
The calling program may use the following procedure to set these variables in the SFDT$
packet:
PROCEDURE SFDT_INITIALIZE(%PACKET: SFDT_PACKET,
INIT_DATE_FORMAT: 6 BIT INTEGER,
INIT_TIME_FORMAT: 6 BIT INTEGER,
INIT_SEPARATOR: 6 BIT STATUS (S’SPACE’:0,
S’DASH’:1),
INIT_CHAR_OFFSET: 6 BIT INTEGER,
INIT_BUFFER_LENGTH: 6 BIT INTEGER,
INIT_BUFFER_ADDRESS: 36 BIT MACHINE POINTER,
INIT_DATE: 36 BIT MACHINE LOGICAL,
INIT_TIME: 36 BIT MACHINE LOGICAL);
BEGIN
PACKET.SFDT_DATE_FORMAT:= INIT_DATE_FORMAT;
PACKET.SFDT_TIME_FORMAT:= INIT_TIME_FORMAT;
PACKET.SFDT_SEPARATOR:= INIT_SEPARATOR;
PACKET.SFDT_CHAR_OFFSET:= INIT_CHAR_OFFSET;
PACKET.SFDT_BUFFER_LENGTH:= INIT_BUFFER_LENGTH;
PACKET.SFDT_BUFFER_ADDRESS:= INIT_BUFFER_ADDRESS;
PACKET.SFDT_DATE:= INIT_DATE;
PACKET.SFDT_TIME:= INIT_TIME;
PACKET.SFDT_PACKET_VERSION:= 1;
END;
The SFDT_INITIALIZE procedure is defined in a PLUS COPY element (see 22.2.2).
For example, the following call will initialize the data entity 'pkt' for date format 4 and
time format 2, which are separated by a dash.
SFDT_INITIALIZE(%pkt,4,2,S’Dash’,0,5,LOC(buffer),TEST_DATE,-1);
These formats start in Q1 of the first word of the buffer; the buffer length is five words
and is stored in buffer using the date stored at TEST_DATE and the current time.
Returns
SFDT$ returns string length in SFDT_NUMBER_CHAR, the offset of the last character
(0, 1, 2, or 3) in SFDT_CHAR_OFFSET, and the error code, if any, in
SFDT_ERROR_CODE.
22–10 7833 1733–004

22.2.2. Calling Sequence
SFDT$–System Standard Format Date and Time
Calling programs need the following procedure declaration to call SFDT$:
PROCEDURE STANDARD_DATE_TIME(%SFDT_PKT_ADDR: SFDT_PACKET)
IMPORTED (‘external-name’);
The external-name may be one of two entry points to SFDT$.
SFDT$P This entry point uses the relocatable version of SFDT$.
SFDT$PG This entry point uses the common bank version of SFDT$.
The type definitions for SFDT_BUFFER and SFDT_PACKET, the initialization procedure
SFDT_INITIALIZE, and the procedure definition for STANDARD_DATE_TIME are available
in elements SFDT$D and SFDT$DG in the SYSLIB file SYS$LIB$*SYSLIB. Element
SFDT$D contains the definitions to call the relocatable version of SFDT$, and SFDT$DG
contains the definitions to call the common bank version of SFDT$.
These elements are obtained with the COPY statement as follows:
COPY(‘elt-name’);
where elt-name may be SFDT$D or SFDT$DG.
SFDT$ Calling Format
STANDARD_DATE_TIME(%pkt);
where pkt is the identifier of a data entity of type SFDT_PACKET.
Returns
If no error occurs, SFDT$ creates the ASCII date/time format string and returns it in the
buffer specified by the calling program.
SFDT$ returns the following variables to the calling program:
SFDT_CHAR_OFFSET
Position in word of the last nonspace character of the ASCII string (0, 1, 2, or 3).
SFDT_NUMBER_CHAR
The number of characters in the string.
7833 1733–004 22–11

SFDT$–System Standard Format Date and Time
SFDT_ERROR_CODE
22.2.3. Example
Negative error code if an error occurs:
1 The buffer length is too short for specified format(s).
2 The date-format index is out of range.
3 The time-format index is out of range.
4 Both date and time formats are zero.
5 An outdated version of the SFDT$ packet is being used.
The following example calls the relocatable version of SFDT$ from a PLUS program to
return the date and time as an ASCII character string.
module;
copy ( ‘sfdt$dg’ );
declare line: sfdt_buffer;
declare pkt: sfdt_packet;
sfdt_initialize ( %pkt, 8, 3, s’space’, 0, 7, loc( line ), -1, -1 );
standard_date_time ( %pkt );
open file ‘sysprint’ stream output;
put file ‘sysprint’ edit ( line ) ( skip, a(28), skip );
close file ‘sysprint’ ;
term
This will store the ASCII string for date format 8 and time format 2, which are separated
by a space. These formats start in Q3 of the first word using current date and time in
the buffer DATE_AND_TIME_LINE. They are six words long.
22.3. SFDTBL$–Month and Day Table
SFDTBL$ is a table of three ASCII character abbreviations for the months of the year and
days of the week. SFDTBL$ is used by the standard date/time routines as a separate
element. The ASCII characters can then be changed easily to incorporate user-defined
abbreviations. Each abbreviation uses one word of storage, with a blank as the fourth
character of the word.
22–12 7833 1733–004

Section 23
SIR$–Symbolic Input/Output Routine
The Symbolic Input/Output Routine (SIR$) performs input, output, and updating on
system data format (SDF) files. Processors call SIR$ to read symbolic input from
• A runstream
• A symbolic element in a program file
• An SDF file
SIR$ can update the symbolic input from an element or file with input from the
runstream.
After reading symbolic input and possibly updating it, the SIR$ routine can write
symbolic output to
• A symbolic element in a program file
• An SDF file
The general capabilities of SIR$ are described in this subsection. The entry points and
functions of SIR$ are described in 23.2.
When reading symbolic input, SIR$ automatically merges correction images and
produces an updated symbolic element that is inserted into a program file. The symbolic
element that contains the symbolic input may be cycled by specifying the desired cycle
in the processor call statement. SIR$ automatically passes to the processor only those
images that pertain to the cycle requested.
Symbolic images can be in any of the coded character sets (CCS) listed in Appendix H.
SIR$ normally handles images in the following CCSs:
• Fieldata images.
• ASCII images. Identified as ASCII_ISO, octal code 01, in Table H–1.
• ASCII-like images. There are 39 CCSs listed in Table H–1 that are defined as being
ASCII-like, or essentially identical to the ASCII_ISO character set for characters in the
octal range of 0000 through 0177.
SIR$ can optionally be initialized to handle, with some restrictions, images in an
additional 22 CCSs. These 22 CCSs are referred to as “other CCSs” in the remainder of
the SIR$ section. This allows SIR$ to process images in all 63 legal CCSs. Note that
CCS octal 076 is reserved for future use and is currently illegal.
7833 1733–004 23–1

SIR$–Symbolic Input/Output Routine
The information for symbolic input and output elements or files (for example, their
names) is obtained from the entries in PARTBL. The information in PARTBL is usually
produced by the PREPRM and PREPRO (see 14.1.1) or PREPF$ (see 14.2) routines from
information specified on the processor call statement.
Some options placed on a processor call statement affect the SIR$ routine. These
options are listed in 23.1.
Depending on which options are specified, SIR$ is directed to
• Write images in Fieldata, ASCII, or without translation.
• Read and check sequence numbers.
• Create symbolic elements from the runstream.
• Update and produce new element cycles.
• List runstream line change statements and change images.
SIR$ reads, processes and writes system data format (SDF) images.
SDF data images from the source input element or file have implicit, sequential line
numbers, beginning with 1. The numbers on runstream correction images refer to the
source input line numbers.
SDF control images in the source input may be passed to the calling program, but the
control images do not have line numbers and do not affect the line numbering of the
source input data images.
See the Data Structures Programming Reference Manual for a description of SDF data
images and control images. See the ECL and FURPUR Reference Manual for a
description of runstream correction images.
Note the following CCS-related restrictions on runstream correction images:
• Runstream line change statements (-n and -n,m), partial line change statements
(-n- and -n,m-) and partial line change editing statements (c/new-data, c,d/new-data/,
/old-data/new-data and /old-data/new-data/) must be Fieldata, ASCII, or ASCII-like
images.
• Runstream partial line change statements (-n- and -n,m-) can only be used to edit
source input images that are Fieldata, ASCII or ASCII-like. That is, source input line n
(first format) or lines n through m (second format) must be Fieldata, ASCII, or
ASCII-like images.
• The CCS of a source input image does not change when it is edited by a partial line
change statement and partial line change editing statements.
• When the partial line change editing statements (c/new-data, c,d/new-data/,
/old-data/new-data, and /old-data/new-data/) are in a different ASCII-like CCS than the
source input image being edited, differences in the graphic representation of
characters may affect the results of SIR$ editing operations.
23–2 7833 1733–004

SIR$–Symbolic Input/Output Routine
Different ASCII-like CCSs often have different graphic characters associated with an
octal value, particularly for octal values of 0200 and over. Conversely, there are
cases where characters in different ASCII-like CCSs have identical graphic
representations but have different octal values. Of particular note in this case are
certain special characters in the ASCII-like ISO 646 CCSs (decimal CCS 17 through
28). For example, the small letter “c” with the cedilla diacritical mark is represented
by the octal value 0134 in ISO_646_Italy (decimal CCS 22); the octal value 0175 in
ISO_646_Spain (decimal CCS 23); and the octal value 0347 in ISO_8859_2 (decimal
CCS 36).
SIR$ character comparisons and replacements are always based on the octal values
of characters in the runstream partial line editing statement and in the source input
image, never on their graphic representation. As a result
− Old-data characters that graphically match a source input image string may result
in an unexpected SIR$ “no find.”
− Old-data characters that do not appear to match a source input image string may
result in an unexpected SIR$ “find.”
− New-data characters may not have the same graphic representation once they
are placed into the source input image.
• Runstream images in CCSs other than Fieldata, ASCII, or ASCII-like can only
represent images to be inserted into the source output following a “-n” line change
statement or images to replace source input images following a “-n,m” line change
statement.
When an updated or new symbolic element is specified on the processor call statement,
the updated or new symbolic is written to the program file. If a two-pass processor call
is made to SIR$ and an update element is not specified on the processor call statement,
the processor must provide a scratch file to hold the updated symbolic for the second
pass. GETPSF$ can be called to get the scratch file. The internal file name of the
scratch file must be in PARTBL+14,15 and PARTBL+16 must be set to zero prior to
entering SIR$.
To read from and write to an SDF file, PARTBL + 16,17 and PARTBL + 29,30 must be
set to zero.
Label Control Record
Whenever symbolic output is written by SIR$, a label control record is the first image
written. The format of the label control record created by SIR$ is the following.
0 5 6 11 12 17 18 29 30 35
0 050 01 030 CCS
1 *SDFF*
7833 1733–004 23–3

SIR$–Symbolic Input/Output Routine
Word 0
S1
S2
S3
S6
050 is the SDF label identifying this as an SDF element.
indicates that a 1-word image follows.
the Fieldata character 'S' identifies this as an SIR$-created file or element.
indicates the CCS of the data records that follow (see Appendix H).
If SIR$ writes a source output element, the element is identified as a Fieldata element if
the label control record CCS is zero; otherwise, it is identified as an ASCII element.
SIR$ Line-Change Control Record
When SIR$ applies runstream corrections to the source input, SIR$ line-change control
records are written to the source output and passed to the calling program. Note that
these are control records that SIR$ writes to the source output; if SIR$ line-change
control records are read in the source input, they are discarded by SIR$.
SIR$ produces two types of SIR$ line-change control records, both of which may be
present in source output produced by SIR$.
The first type contains the actual text of the runstream line change statement or partial
line change statement. It is used primarily by processors when producing
comprehensive 'V' option listings of source input line numbers and runstream
corrections. The control record format follows.
0 5 6 11 18 35
0 052 n 0
1 line-change statement
..
n
23–4 7833 1733–004

Word 0
S1
S2
H2
052 indicates that this is an SIR$ line-change control record.
SIR$–Symbolic Input/Output Routine
n specifies the length of the line change statement or partial line change statement
in words 1 through n.
Zero.
When this control record is written to the source output and passed to the calling
program, the CCS of the line change statement image is processed identically to a
runstream data image of the same CCS.
The SIR$ line-change control record for a -n line change statement is written to the
source output immediately after source input line n. The SIR$ line-change control record
for a -n,m line-change statement or for a -n- or -n,m- partial line change statement is
written to the source output immediately after source input line n-1.
The second type of SIR$ line-change control record is used internally by SIR$ and is not
directly passed to the calling program. This control record is written by SIR$ whenever
source input images are deleted by runstream corrections. The record contains a count
of the number of source input images deleted immediately before the source input
image that follows this control record. On the second and subsequent passes, SIR$
uses this control record to calculate source input line number and source input image
deletion information that is returned to the calling program. The control record format
follows.
0 5 6 11 18 35
0 052 0 number-of-images-deleted
Word 0
S1
S2
H2
052 indicates that this is an SIR$ line-change control record.
Zero.
The number of source input images deleted immediately before the next source
input image.
7833 1733–004 23–5

SIR$–Symbolic Input/Output Routine
Data Record
The first word of each data record is the image control word. For data records written by
SIR$, the format of the image control word is as follows:
0
0 1 11 12 17 18 23 24 29 30 35
0
image length
(words)
previous images
deleted flag
delete cycle
number
new images flag
start cycle
number
S6 is the element cycle at which the image was added; S4 is the cycle at which it was
deleted. If the image is added on the latest cycle (after cycle zero), the new flag is set.
The calling processor marks the line as "NEW". If this is not a new image and any
previous images were deleted on the cycle, S3 is nonzero.
When the symbolic input is from a FURPUR-formatted element file, the tape label block
is read prior to entering SIR$. SIR$ then treats it as a program-file element. After SIR$
is closed, the tape is positioned in front of the new element label block.
SIR$ contains its own D-bank; however, all D-bank references in SIR$ are made using
index registers. This allows the SIR$ D-bank to be located above the 65K addressing
boundary.
23.1. SIR$–Control Options
SIR$ uses options to control the input and output of the symbolic elements. Most of the
Unisys language processors (FTN, MASM, ACOB, NUALG, etc.) and system processors
(DATA, ELT, PDP, and Collector) use the SIR$ routine to obtain input. The following
options are available in most language system processors:
G
H
I
Input is compressed symbolic in columns 1 through 80 of the symbolic images.
Applies only with I option.
Input contains sequence numbers in columns 73 through 80 of the images. Applies
only with I option.
Read images from the runstream and insert them into a new symbolic. If the I
option is present without any source input (SI) specification, SIR$ reads images from
the runstream and passes them to the caller. In this case, if the calling program is a
multipass processor, a scratch file (usually PSF$) must be provided so that the
source images can be processed on the second and subsequent passes.
23–6 7833 1733–004

J
K
SIR$–Symbolic Input/Output Routine
Input contains compressed symbolic images in columns 1 through 72 of the images
and sequence numbers in columns 73 through 80. These sequence numbers are
not checked by either the J option or the K option. Applies only with the I option.
Check sequence numbers in columns 73 through 80 of the symbolic images (valid
only with H and I options).
P and Q
U
W
The P and Q options are used in combination to specify the CCSs of source output
images produced by SIR$. A detailed description of source output operations
follows this list of options.
Read change images from the runstream, apply them to the symbolic input element,
and produce a new cycle of the symbolic element.
List line-change statements and change images.
SIR$ Source Output
When the source output portion of PARTBL (Words 14 through 26) has been filled by the
calling program, SIR$ produces a source output file or element. When the I option is
specified, the source output is created from runstream images. When the I option is not
specified, the source output is created from source input images, possibly modified by
corrections contained on runstream images.
The CCS of images in the source output is controlled by the various combinations of the
P and Q options and by the CCS of the images in the source input and the runstream.
In general, the P option requests Fieldata source output, the Q option requests ASCII
source output, and both the P and Q options request source output without translation.
7833 1733–004 23–7

SIR$–Symbolic Input/Output Routine
The following table lists SIR$ source output operations in greater detail. The columns of
the table list the P option, the Q option, and both the P and the Q options. Note that the
"neither P nor Q option" case is discussed later in this section. There are separate rows
in the table for input images in Fieldata, ASCII, ASCII-like CCSs, the 22 "other" CCSs, and
the illegal CCS. The input image may originate in either the runstream or the source
input. The intersection of the columns and rows is the SIR$ source output action with
this combination of options and input image CCS type.
Input Image Type
P Option
Fieldata Unchanged
Fieldata image
ASCII Translated to
Fieldata image
ASCII-like Translated to
Fieldata image
"Other CCS" Error; image
not written
Illegal CCS Error; image
not written
Q Option
Translated to
ASCII_ISO
image
Unchanged
ASCII image
Unchanged
ASCII-like
image
Error; image
not written
Error; image
not written
P and Q
Options
Unchanged
Fieldata image
Unchanged
ASCII image
Unchanged
ASCII-like
image
Unchanged
image in
"other" CCS
Error; image
not written
In summary, when the P option is specified, the source output contains only Fieldata
images; when the Q option is specified, the source output can contain images in ASCII
and any of the 39 ASCII-like CCSs; and when both the P and the Q options are specified,
the source output can contain images in any of the 63 legal CCSs.
When neither the P nor the Q option is specified, the CCS of source output images
depends on the presence of the I option.
When the I option is specified, both the P and the Q option are assumed. Runstream
images in all 63 legal CCSs can be written unchanged to the source output. The "P and
Q options" column of the preceding table lists the SIR$ source output action for the
runstream image types listed in the rows.
When the I option is not specified, the CCS of the source output image is determined as
follows:
• When a source input image is written to the source output, it is written unchanged
and retains its CCS.
• When a runstream image following a -n line-change statement is written to the
source output, the CCS of the output image is based on the CCS of source input
image n, as shown in the table that follows.
• When a runstream image following a -n,m line-change statement is written to the
source output, the CCS of the output image is based on the CCS of source input
image m, as shown in the table that follows.
23–8 7833 1733–004

SIR$–Symbolic Input/Output Routine
The columns of the table list the source input image type for image n or m, described
above. The types are Fieldata, ASCII, or ASCII-like and other CCSs. The rows of the
table list the runstream image type to be written to the source output. The types are
Fieldata, ASCII, or ASCII-like and other legal CCSs. The intersection of the columns and
rows is the SIR$ source output action with this combination of source input image CCS
type and runstream image CCS type.
Runstream
Input Image
Type
Source Input
Image is
Fieldata
Fieldata Unchanged
Fieldata image
ASCII or
ASCII-like
Translated to
Fieldata image
"Other CCS" Error; image not
written
Source Input
Image is ASCII
or ASCII-like
Translated to
ASCII_ISO
image
Unchanged
ASCII,
ASCII-like image
Error; image not
written
Source Input
Image is
"Other" CCS
Unchanged
Fieldata image
Unchanged
ASCII,
ASCII-like
image
Unchanged
image in
"other" CCS
In summary, when the source input image is Fieldata the P option is assumed; when the
source input image is ASCII or ASCII-like, the Q option is assumed; and when source
input image is in another CCS, both the P and the Q options are assumed.
Note that when the calling program is a multipass processor, the second and
subsequent passes usually read the source output that is written by SIR$ during the first
pass. This means that the CCS of an image processed during the first pass may be
different when the same image is processed during the second and subsequent passes.
For example, if the P option is specified, an ASCII-like source input image in decimal CCS
41 is written to the source output in Fieldata. This means that on the second pass the
image can no longer be identified as a CCS 41 image and, in fact, cannot be
distinguished from images that were originally Fieldata, ASCII, or any of the 39 ASCII-like
CCSs. A more extreme example is that if both the P and Q options are not either
specified or assumed, source input images in the 22 “other” CCSs are not written to the
source output. This means that on the second pass the images cannot be passed to the
calling program since they were not written to the source output on the first pass.
7833 1733–004 23–9

SIR$–Symbolic Input/Output Routine
Character Set Change Control Record
When the source output contains images in more than one CCS, Character Set Change
control records are written by SIR$ each time an image to be written is in a different
CCS than the previously written image. The Character Set Change control record
indicates the CCS of one or more images that follow. The control record format is as
follows:
0 5 6 11 30 35
042
Word 0
0 CCS
S1
S2
S6
042 indicates that this is a Character Set Change control record.
Zero.
The CCS of the data records that follow.
23.2. SIR$ Entry Points
The SIR$ routine contains six entry points
OPNSR$ Initialize SIR$ for symbolic input and output.
INISR$ Initialize SIR$ with additional information.
GETAS$ Read a symbolic image in ASCII.
GETSR$ Read a symbolic image in Fieldata.
GETNM$ Read a symbolic image without translation.
CLOSR$ Close SIR$ input and output.
Note: Either OPNSR$ or INISR$ may be called for initialization. Both routines cannot
be called on the same pass.
23.2.1. OPNSR$–Open SIR$ Input and Output
OPNSR$ initializes SIR$ to allow input and output of symbolic data.
OPNSR$ provides first or second pass initialization for the GETAS$, GETSR$, and
GETNM$ read symbolic image routines. If the symbolic input is from a program file or
tape, the System Data Format Input (SDFI) routine is opened. If the symbolic output is
specified, the System Data Format Output (SDFO) routine is opened.
23–10 7833 1733–004

SIR$–Symbolic Input/Output Routine
If input is from an element, the SDF type is tested. If S3 of the label control record is
nonzero and not the Fieldata character "S", the message 'SI IS NOT SIR TYPE' is printed.
All cycling information in the control words is then ignored.
Calling Sequence
LMJ X11,OPNSR$
error return
normal return
Returns
OPNSR$ takes the error return if:
• SDFI is unable to open the symbolic input. Register A5 contains the I/O error status
code from SDFI.
• An attempt is made to process an invalid SDF file or element. Register A5 is set to
zero. The associated error message is
INVALID SDF LABEL WORD w
where w is the first two words of the element or file printed in Fieldata.
23.2.2. INISR$–Initialize SIR$ Input and Output
INISR$ initializes SIR$ to allow input and output of symbolic data. INISR$ performs the
first or second pass initialization functions described for OPNSR$ and additionally allows
the calling program to control certain SIR$ actions.
Calling Sequence
L A4,initialization-word
LMJ X11,INISR$
error return
normal return
The initialization-word is provided by the caller to control certain SIR$ actions.
The initialization-word can contain
• A list of specific SDF control record types that SIR$ should not pass to the calling
program.
• A flag to indicate that SIR$ should not create source output if certain conditions are
met.
• A flag to indicate that when an ASCII-like image is passed to the calling program,
SIR$ should include the CCS for the image.
• A flag to indicate that SIR$ should pass images in all 63 legal CCSs to the calling
program and should include the CCS for the image.
7833 1733–004 23–11

SIR$–Symbolic Input/Output Routine
Control Records to Pass
On entry, bits 4 through 35 of A4 specify which SDF control records SIR$ should not
pass to the calling program. If bit n is set, then the control record type 0103-n is not
passed to the calling program. The control record is still written to the source output by
SIR$.
Example
If A4 equals 013 on a call to INISR$, bits 32, 34, and 35 are set, or bits 040, 042, and 043
in octal. This initializes SIR$ so that control record types 0103-040 = 043, 0103-042
= 041, and 0103-043 = 040 are not passed to the calling program.
Source Output Control
If bit 0 of A4 is set, SIR$ checks for the following conditions:
• The output is to a scratch file and not to a source output element (PARTBL+16=0).
• The input is not from tape.
• There are no changes to the symbolic input.
If these conditions exist, SIR$ does not write to the processor's scratch file on the first
pass. On subsequent passes, SIR$ rereads the input element. If these conditions are
met, SIR$ performs approximately 75-percent fewer I/Os on the first pass than if SIR$
were called with OPNSR$.
Example
@MASM,S non-tape-si-element,ro-element
@EOF
In this example, SIR$ does not send unused output to the processor scratch file when
the Assembler sets register A4 to negative and calls INISR$ instead of OPNSR$.
Return CCS Identifier
Fieldata, ASCII, and ASCII-like symbolic images can be passed to the calling program in
Fieldata by using the GETSR$ entry point, in ASCII by using the GETAS$ entry point, or
without translation by using the GETNM$ entry point.
If bit 1 of A4 is set, SIR$ stores the CCS identifier in S6 of A0 for all images passed to
the calling program in ASCII (GETAS$ and GETNM$ entry points). This initialization
option allows the caller to identify the actual CCS associated with each image passed in
ASCII, which may be necessary for proper processing of images in different ASCII-like
CCSs.
If bit 1 of A4 is clear or if the OPNSR$ initialization entry point is called, SIR$ stores 01 in
S6 of A0 for all images passed to the calling program in ASCII (GETAS$ and GETNM$
entry points) and 00 in S6 of A0 for all images passed to the calling program in Fieldata
(GETSR$ and GETNM$ entry points).
23–12 7833 1733–004

SIR$–Symbolic Input/Output Routine
Return Images in All CCSs
Symbolic images in the 22 "other" CCSs cannot be translated by SIR$ into Fieldata or
ASCII, so these images cannot be passed to the calling program using the GETSR$ or
GETAS$ entry points.
If bit 2 of A4 is set and the GETNM$ entry point is called to read a symbolic image, SIR$
passes images in Fieldata, ASCII, ASCII-like CCSs, and the 22 "other" legal CCSs to the
calling program without translation. SIR$ stores the CCS identifier of the image in S6 of
A0.
If bit 2 of A4 is clear or if the OPNSR$ initialization entry point is called, SIR$ does not
pass images in the 22 “other” CCSs to the calling program, but instead returns an error.
This ensures that only Fieldata, ASCII, and ASCII-like images are passed to a calling
program, unless the program has explicitly set bit 2 in A4 to indicate that it can handle
images in the 22 “other ” CCSs.
23.2.3. GETAS$–Get Symbolic Image in ASCII
The GETAS$ entry point is called to obtain the next input image from the source input or
the runstream and to pass the image to the calling program in ASCII. Input images in
Fieldata are translated to the ASCII_ISO CCS and passed to the calling program. Input
images in ASCII and ASCII-like CCSs are passed without change to the calling program.
An exception is that when the P option is either specified or assumed, requesting
Fieldata source output, lowercase alphabetics are changed to uppercase alphabetics
when the image is passed to the calling program. Input images in the 22 “other” CCSs
are not passed to the calling program, but instead result in an error return.
Calling Sequence
L A0,(buffer-length,buffer-addr)
LMJ X11,GETAS$
error return
end-of-file return
normal return
where:
buffer-length
The length in words of the buffer into which the symbolic input images are read.
buffer-addr
The address of the buffer into which symbolic input images are read.
7833 1733–004 23–13

SIR$–Symbolic Input/Output Routine
Returns
A call to GETAS$ obtains the next symbolic image from the source input. The image is
returned in the calling program buffer. The images are always returned in the ASCII
character set. If the image was read in Fieldata, it is translated to ASCII before it is
returned to the calling program.
If the buffer is longer than the image read, the buffer is blank-filled to the end. If the
buffer is shorter than the image read, only the part of the image that will fit in the buffer
is returned; the rest of the image is lost. SIR$ reads up to a 63-word image and can be
configured to read up to 2047 word images.
If symbolic output is specified, SIR$ writes the image. Note that even though the image
is passed to the calling program in ASCII, this does not affect the CCS of the image
when it is written to the source output. As previously described, the P and Q options
determine the CCS of the output image. For example, a Fieldata image is translated to
ASCII_ISO when passed to the calling program, but the image would still be written to
the source output in Fieldata if the P option or both the P and the Q options are
specified.
If SIR$ takes an error return because of an unrecoverable I/O error, A5 contains the I/O
error status code. If SIR$ takes an error return because of a line-change statement error,
partial line-change statement error, partial line-change editing statement error, source
input image CCS error, or source output image CCS error, A5 is zero and A0 contains a
print control word for a message describing the error. The calling program can do an
ER PRINT$ to print the Fieldata error message.
SIR$ takes the end-of-file return when there are no more symbolic input images to read.
The following information is returned to the calling program in registers A0 through A5
when the normal return is taken:
A0
A1
(S6)
If SIR$ was initialized with OPNSR$ or if SIR$ was initialized with INISR$ and A4
bits 1 and 2 were both clear, the ASCII_ISO CCS identifier 01 is returned. If
SIR$ was initialized with INISR$ and either A4 bit 1 or 2 was set, the CCS
identifier of the image is returned. For a Fieldata image translated to ASCII, the
ASCII_ISO CCS identifier 01 is returned.
The SDF image control word for the record read. If bit 0 (leftmost bit) of register
A1 = 1, the record returned to the caller is a control record, and registers A2 through
A5 are undefined.
23–14 7833 1733–004

A2
A3
A4
A5
(Q1)
(Q2)
(H2)
SIR$–Symbolic Input/Output Routine
ASCII "#" symbol (octal 043) if the sequence numbers in columns 73 through 80
are not sequential. Otherwise, an ASCII space (octal 040). This applies only
with the H and K options.
ASCII "*" symbol (octal 052) if the image came from the runstream. Otherwise,
an ASCII space (040).
A 2-digit ASCII cycle number for the image.
Contains one of the following in ASCII:
• The characters "∆NEW" (if this is a new image).
• The characters "xxxx" where xxxx is a left-justified, space-filled decimal number.
It is preceded by a minus sign if 3 digits or less. This indicates the number of
images deleted prior to this image.
• Four space characters.
The current line number of the symbolic input element. Register A4 = 0 for new
images read from the runstream. The line number for each image is the same for all
passes.
An actual or generated CTS line number.
7833 1733–004 23–15

SIR$–Symbolic Input/Output Routine
23.2.4. GETSR$–Get Symbolic Image in Fieldata
GETSR$ obtains a symbolic input image in Fieldata and returns it to the calling program.
If symbolic output is specified, SIR$ writes the image to the output file or element.
Calling Sequence
L A0,(buffer-length,buffer-addr)
LMJ X11,GETSR$
error return
end-of-file return
normal return
where:
buffer-length
The length in words of the buffer into which the symbolic input image is read.
buffer-addr
The address of the buffer into which the symbolic input image is read.
Returns
The GETSR$ entry point is called to obtain the next input image from the source input or
the runstream and to pass the image to the calling program in Fieldata. Input images in
ASCII and ASCII-like CCSs are translated to Fieldata and passed to the calling program.
Input images in Fieldata are passed without change to the calling program. Input images
in the 22 "other" CCSs are not passed to the calling program, but instead result in an
error return.
If the buffer is longer than the Fieldata image, the buffer is filled with Fieldata spaces to
the end. If the buffer is shorter that the image, only buffer-length words are returned;
the remainder of the image is lost. SIR$ reads images up to 63 words and can be
configured to read images up to 2,047 words.
If symbolic output is specified, SIR$ writes the image. Note that even though the image
is passed to the calling program in Fieldata, this does not affect the CCS of the image
when it is written to the source output. As previously described, the P and Q options
determine the CCS of the output image. For example, an ASCII-like ISO_8859_5
(decimal CCS 39) image is translated to Fieldata when passed to the calling program, but
the image would still be written to the source output as an ISO_8859_5 image if the Q
option or both the P and the Q options are specified.
If SIR$ takes an error return, the information returned is the same as described for
GETAS$ in 23.2.3.
SIR$ takes the end-of-file return when there are no more symbolic images to read in
either the source input or the runstream.
The following information is returned to the calling program in registers A0 through A5
when the normal return is taken:
23–16 7833 1733–004

A0
A1
A2
A3
(S6)
00, the Fieldata CCS identifier.
SIR$–Symbolic Input/Output Routine
The SDF image control word for the image read. If bit 0 of register A1 = 1, the
record returned to the caller is a control record and registers A2 through A5 are
undefined.
(S1)
(S2)
(S3)
(H2)
Always contains a Fieldata space (octal 05).
Fieldata "#" symbol (octal 03) if the sequence numbers in columns 73 through 80
are not sequential; otherwise, a Fieldata space (octal 05). This applies only with
the H and K options.
Fieldata "*" symbol (octal 050) if the image came from the runstream; otherwise,
a Fieldata space (octal 05).
A 3-digit Fieldata cycle number for the image.
Contains one of the following in Fieldata characters:
• The 6 characters "∆∆∆NEW" if this is a new image.
• A decimal number indicating the number of images deleted prior to this image.
If the number is 5 digits or less, it is preceded by a minus sign (octal 041) and
the digits are left-justified and space-filled on the right. If the number is 6 digits,
it is not preceded by a minus sign.
• Six space characters.
7833 1733–004 23–17

SIR$–Symbolic Input/Output Routine
A4
A5
The current line number of the symbolic input file or element. Register A4 is zero for
new images read from the runstream. The line number for each image is the same
for all passes.
An actual or generated CTS line number.
23.2.5. GETNM$–Get Symbolic Image Without Translation
GETNM$ obtains a symbolic input image and returns it to the calling program with no
translation. If symbolic output is specified, SIR$ writes the image to the output file or
element.
Calling Sequence
L A0,(buffer-length,buffer-addr)
LMJ X11,GETNM$
error return
end-of-file return
normal return
where:
buffer-length
The length in words of the buffer into which the symbolic input images are read.
buffer-addr
The address of the buffer into which the symbolic input images are read.
Returns
The GETNM$ entry point is called to obtain the next input image from the source input
or the runstream and to pass the image to the calling program without translation. Input
images in Fieldata, ASCII, and the 39 ASCII-like CCSs are passed without change to the
calling program. An exception is that when the image to be returned is ASCII or
ASCII-like and when the P option is either specified or assumed, requesting Fieldata
source output, lowercase alphabetics are changed to uppercase alphabetics when the
image is passed to the calling program. If SIR$ was initialized with INISR$ and A4 bit 2
was set, input images in the 22 “other” CCSs are passed to the calling program. If SIR$
was initialized with OPNSR$ or if SIR$ was initialized with INISR$ but A4 bit 2 was clear,
input images in the 22 “other” CCSs are not passed to the calling program, but instead
result in an error return.
23–18 7833 1733–004

SIR$–Symbolic Input/Output Routine
If the buffer is longer than the image, the buffer is filled to the end. If the image is
Fieldata, the buffer is filled with Fieldata spaces, octal 05. If the image is ASCII or
ASCII-like, the buffer is filled with ASCII spaces, octal 040. If the image is in an "other"
CCS, the buffer is filled with binary zero characters, octal 0. If the buffer is shorter than
the image, only “buffer-length” words are returned; the remainder of the image is lost.
SIR$ reads images up to 63 words and can be configured to read images up to 2,047
words.
If symbolic output is specified, SIR$ writes the image. Note that even though the image
is passed to the calling program without translation, this does not affect the CCS of the
image when it is written to the source output. As previously described, the P and Q
options determine the CCS of the output image.
If SIR$ takes an error return, the information returned is the same as described for
GETAS$ in 23.2.3.
SIR$ takes the end-of-file return when there are no more symbolic images to read in
either the source input or the runstream.
When SIR$ takes a normal return, information is returned to the calling program in
registers A0 through A5. If the passed image is Fieldata, the return information is as
described in 23.2.4 for GETSR$. If the passed image is not Fieldata (ASCII, ASCII-like,
or “other”), the return information is as described in 23.2.3 for GETAS$.
23.2.6. CLOSR$–Close SIR$ Input and Output
CLOSR$ closes the symbolic input file. If there is symbolic output, CLOSR$ closes the
symbolic output file.
CLOSR$ provides termination for the first and all subsequent passes. SIR$ closes the
SDFI routine. If symbolic output was specified, SIR$ closes the SDFO routine. If the call
to SIR$ is a first pass and the symbolic output is an element, an entry is made in the
symbolic output program file through the Program File Package Insert routine (ER PFI$).
Calling Sequence
LMJ X11,CLOSR$
error return
normal return
Error Return
SIR$ takes the error return when SDFO is unable to close the symbolic output. Two
other error returns are possible when source output is to be written to a program file
element. SIR$ takes the error return when the text length is over 262,143 sectors or
when ER PFI$ returns an error to SIR$.
In the case of an SDFO error, register A5 contains the I/O error status code. In the two
other cases, A5 is zero. In the case of the text length over 262,143 sectors, register A2
contains the sector count, which is always at least octal 01000000. In the case of an
ER PFI$ error, register A2 contains the PFI$ error status code, which is always less than
octal 0100. (See the ER Programming Reference Manual.)
7833 1733–004 23–19

SIR$–Symbolic Input/Output Routine
23.3. External Labels
SIR$ contains a number of data areas that the calling program may access.
• SIRIB$
The start of the 1,792-word input buffer.
• SIROB$
The start of the 1,792-word output buffer.
• SIRP2$
Set to one in CLOSR$ to identify a second pass call to OPNSR$, INISR$,
GETAS$, and GETNM$.
• SIRSDFIFCT$
The start of the SDFI file control table.
• SIRSDFOFCT$
The start of the SDFO file control table.
The calling program may not use the SIRIB$ or SIROB$ buffers between calls to
OPNSR$ or INISR$ and CLOSR$.
23.4. SIR$–Multipass Capability
SIR$ allows many passes to be made over the input element if a scratch file or output
element is available in PARTBL+14,15. (For exceptions, see INISR$, 23.2.2.) For
reusable processors, SIR$ must be told when to initialize itself to process the element
designated on the next processor call statement that INFOR CLIST reads. The calling
program must store zero into the externally defined cell SIRP2$ in SIR$. No other action
is required.
23.5. Compressed Symbolic Elements
To minimize the number of cards required to contain a symbolic element, the FURPUR
processor can compress strings of blanks in symbolic images before punching the
element. SIR$ expands the compressed images on input.
A compressed symbolic image card deck is produced when the appropriate options are
used on the FURPUR @PCH control statement. (See the ECL and FURPUR Reference
Manual.) SIR$ converts compressed card image decks to SDF images upon initial input
when the I and G or J options are specified on the processor call statement (see G.1).
The first card punched is an @ELT or @PDP control statement with the appropriate
options. Following the control statement are the cards that contain compressed
symbolic images.
The compressed image consists of a stream of characters in the following format:
23–20 7833 1733–004

xccc...cyxccc...cz
where:
x Number of characters C (1 ≤x ≤ 37)
y 40 + Number of blanks (41 < y ≤ 77)
z 40 = End of image
SIR$–Symbolic Input/Output Routine
The number of characters in a string is limited to 37; the number of blanks is limited to
36. If either is larger, a new x or y is initiated.
In addition to the x, y, and z characters, two other special characters are used:
41 character
indicates the end of images in this element.
0 character
is a special character in column 80 if a new x will begin in column 80. The x is
moved to the next physical card and the 0 is placed in column 80.
The compressed images immediately follow one another on the physical card and
continue to the next card when the end of card is reached. The punch routine begins
each physical card with an x, y, or z by breaking an x string at the end of the card and
starting a new string on the next card. This guarantees a nonzero character in the first
character position of the card. A compressed blank image is represented by a 40
character. The physical card may contain compressed image characters in columns 1
through 80.
Compressed images are not retained in the program file. SIR$ expands the images and
stores them in the program file in SDF format.
Compressed image symbolic input is an SIR$ configurable feature.
7833 1733–004 23–21

SIR$–Symbolic Input/Output Routine
23–22 7833 1733–004

Section 24
Program Trace Routine
The Program Trace Routine (SNOOPY) is a routine that traces through programs. It is
used with assembly language programs. In batch mode, SNOOPY provides information
about every instruction executed and the effect it had. In demand mode, SNOOPY is a
powerful diagnostic routine that gives the caller control over the trace operation. The
following paragraphs describe how to use SNOOPY in batch mode. Large printouts may
be produced.
A program that is being traced functions the same as a program that is not being traced
except that:
• Execution time is slower. This can affect I/O timing, which might be relevant to the
program being diagnosed.
• Contingencies that would normally error terminate the activity being traced
terminate EXIT$.
The following restrictions apply to SNOOPY:
• SNOOPY must be part of the program's main segment (see the Collector
Programming Reference Manual).
• Tracing terminates if the main segment is reloaded.
• Only one activity may be traced at a time unless the caller uses duplicate copies of
SNOOPY.
• The program cannot be traced if it is running in real-time mode.
• No activity contingency routine may exist for the activity being traced.
• The only I/O Executive requests permitted are IO$ and IOW$.
• Byte instructions and J-register (character addressing) mode for the 1100/60,
1100/70, and 1100/80 are not traced. The EIS instructions for the 1100/60 and
1100/70 are not simulated.
• The major register set must be available.
7833 1733–004 24–1

Program Trace Routine
• The following Executive requests (ERs) are supported with packet dumps and
register displays:
ABORT$ DATE$ PFS$
ACSF$ EDJS$ PFUWL$
APCHCA$ ERR$ PFWL$
APCHCN$ EXIT$ NCHA$
APNCHA$ FACIL$ PRINT$
APRINT$ FACIT$ PRNTA$
APRNTA$ FITEM$ PRTCA$
APRTCA$ FORK$ PRTCN$
APRTCN$ IALL$ PSR$
APUNCH$ IO$ PUNCH$
AREAD$ IOW$ READ$
AREADA$ LCORE$ READA$
ATREAD$ LOAD$ SETC$
BANK$ MCORE$ SNAP$
BDI$ MCT$ SWAIT$
CEND$ MSCON$ SYMB$
COM$ OPT$ TDATE$
COND$ PCHCA$ TFORK$
CRTN$ PCHCN$ TIME$
CSF$ PCT$ TREAD$
CTS$ PFD$ TWAIT$
CTSA$ PFI$ WAIT$
CTSQ$
Other ERs pass parameters using the A0 and A1 registers only, but they do not
provide full packet display.
• SNOOPY recognizes the following OS 2200 instruction mnemonics:
AAIJ, AH, AMA, ANA, AND, ANH, ANMA, ANT, ANU, ANX, AT, AU, AX, BT, CDU,
DA, DAN, DDC, DEC, DEC2, DF, DFA, DFAN, DFD, DFM, DFP, DFU, DI, DJZ, DL,
DLM, DLN, DLSC, DS, DSA, DSC, DSF, DSL, DTE, EDC, ENZ, ER, EX, FA, FAN, FCL,
FD, FEL, FM, HJ, INC, INC2, J, JB, JC, JDF, JFO, JFU, JGD, JK, JMGI, JN, JNB,
JNC, JNDF, JNFO, JNFU, JNO, JNS, JNZ, JO, JP, JPS, JZ, LA, LBJ, LCF, LDJ,
LDSC, LDSL, LIJ, LMA, LMJ, LNA, LNMA, LPD, LR, LSC, LSSC, LSSL, LUF, LX, LXI,
LXM, MASG, MASL, MCDU, MF, MI, MLU, MSE, MSG, MSI, MSLE, MSNE,
MSNW, MSW, NOP, OR, PAIJ, SA, SAS, SAZ, SE, SFS, SFZ, SG, SIL, SLE, SLJ,
SMA, SNA, SNE, SNW, SNZ, SN1, SPD, SP1, SR, SSA, SSC, SSL, SW, SX, SZ, TCS,
TE, TEP, TG, TLE, TLEM, TN, TNE, TNW, TNZ, TOP, TP, TS, TSS, TW, TZ, XOR.
24–2 7833 1733–004

24.1. Calling Sequence
There are two formats available for calling SNOOPY.
Format 1
SLJ SNOOPY$
+ mode-bits,termination-addr . mode-word
where:
mode-bits (bits 0 through 17 where bit 0 is the leftmost bit)
Program Trace Routine
Bit 17 controls quarter-word mode sensitivity. If bit 17 of the mode word is set,
SNOOPY simulates quarter-word mode for checkout of quarter-word sensitive
programs on machines without quarter-word hardware. If bit 17 is clear,
SNOOPY uses either third- or quarter-word mode, depending on the mode set in
the Processor State Register (PSR) on entry. If bit 18 is set, the mode word
suppresses the solicitation of commands at the beginning and end of a trace
when using SNOOPY in demand mode.
termination-addr (bits 18 through 35)
Format 2
Tracing begins with the instruction following the mode word. Tracing continues
until the termination address (termination-addr) is reached or until another
termination condition is encountered.
SLJ TON$
Tracing begins following the SLJ instruction and continues until it encounters a
termination condition. The quarter-word mode sensitivity is unchanged with this
format.
24.2. Terminating Trace
Tracing is terminated in batch mode by any of the following:
• Reaching the specified termination address. Program execution continues.
• Using the SLJ TOFF$ instruction (program execution continues). If an SLJ TOFF$
instruction is executed outside of the trace routine, it has no effect.
• Using the ER EXIT$ instruction (see the Exec ER Programming Reference Manual).
This not only terminates SNOOPY, but it also terminates the activity being traced.
• Encountering a program contingency of types 1, 2, 7, or 12 for which standard
system action has been specified. The activity being traced is terminated by EXIT$.
7833 1733–004 24–3

Program Trace Routine
Tracing can be terminated in batch or demand mode with the following methods:
• Use the TOFF$ command (see 24.4.2). Program execution continues.
• Use the EXIT$ command (see 24.4.2)
24.3. Symbol Tables
When using SNOOPY, the u-field of the instruction is edited in octal if it does not refer to
control storage.
The calling program can provide a symbol table to SNOOPY using Fieldata characters
instead of octal values when the u-field falls within the address range of the program
being traced. To do this, store a value in the externally defined location SYMTB$.
SNOOPY uses the symbol table while tracing a program. The value stored in SYMTB$
has the following form:
0 17 18 35
nbr-of-entries table-addr
H1 H2
The symbol table at the specified address is an array of three-word entries in the form:
0 high +1 low
1 Fieldata symbol name or address of long name
2 bits symbol address
H1 H2
If the rightmost bit of bits (bit 17) is set, SNOOPY assumes word 1 of the entry is the
address of a 7- to 12-character Fieldata symbol instead of a 1- to 6-character Fieldata
symbol. This accommodates long labels.
The next word after the last entry may be another symbolic table descriptor word. This
occurs if bit 1 is set in the last entry of the symbol table. SNOOPY searches the symbol
table to which it points in the same fashion. This may be repeated to any level desired.
However, circularity must be avoided (in other words, pointing to the address of a
higher-level symbol table).
If the u-field of an instruction is between the low- and high-address values, edit the
u-field as the symbol given by the second word of the entry, plus or minus an offset
calculated from the symbol address in the third word. If the nbr-of-entries parameter of
SYMTB$ is zero as it is initially, all u-fields outside control storage are edited in octal
except TOFF$ and a number of ER indexes.
24–4 7833 1733–004

24.4. Demand Mode Operation
Program Trace Routine
The caller has a great deal of control over the behavior of SNOOPY in demand mode.
SNOOPY examines the program control table (PCT) to compute storage limits and the
contingency routine address.
When SNOOPY traces a demand program, the amount of output that SNOOPY produces
is reduced (relative to batch mode) because of the low-speed output devices. In
particular, header and trailer messages are brief, registers are dumped only on request,
and line length may be restricted. Further control over printing may be obtained by using
commands described in 24.4.2.
For demand programs, SNOOPY operates in two modes.
• Trace mode, in which instructions are traced
• Command mode, in which the caller uses commands that direct SNOOPY's
operation
SNOOPY enters command mode under these circumstances.
• On entrance, before tracing any instructions, unless mode bit 16 was set
• When the Remote Break (RBK) contingency occurs (@@X C)
• On completing the number of instructions specified by a SKIP or a numeric
command
• When encountering a condition specified by the BREAK or TRAP command
• When an instruction is executed at an address specified on a CAPTUR command
• At trace termination, unless mode bit 16 was set
In command mode, the prompt is “C--”. SNOOPY solicits required parameter fields by
indicating the nature of the required parameter. More than one command can be
entered on any line solicited in command mode (including parameter lines).
Delimiters separate the commands and parameters. A delimiter is any character not in
the set (A through Z, 0 through 9, $, or -). Excess blanks are ignored. If any other
consecutive delimiters are encountered, the effect is the same as the STEP command.
That is, if answering “C--” with a line consisting of “////”, it has the same effect as four
STEP commands.
In certain cases, specific delimiters are required. To omit a parameter entirely, follow the
delimiter that terminated the command by another (nonblank) delimiter (for example,
“PRINT/”). Trace mode is suspended, the last instruction is printed, and a soliciting
message appears under the above six circumstances.
7833 1733–004 24–5

Program Trace Routine
In each of the following circumstances, SNOOPY ignores all commands on the line after
the last one performed; they can be reentered if desired.
• Trace termination (unless mode bit 16 was set).
• The @@X C sequence interrupts the trace.
• SNOOPY encounters an invalid command.
• A CHANGE, TOFF$, or EXIT$ command is used without a trailing asterisk.
Entering a blank line (carriage return) in reply to the “C--” has the same effect as the
STEP command. A blank line response to a parameter request may be erroneous or may
have a special meaning, depending on the nature of the command.
To enter an Executive control statement, answer a command solicitation by entering a
line beginning with the character %. The remainder of the line should be an Executive
control statement without the initial @ character. The statement must be legal for
submission to the CSF$ Executive Request function. SNOOPY converts the initial %
character to an @ and submits the resulting image to CSF$.
If the CSF request is processed normally, the status bits from register A0 are displayed
and SNOOPY solicits the next command. Otherwise, SNOOPY intercepts the
appropriate contingency and prints the message “CSF$ ERROR” followed by command
solicitation. For example, to assign a temporary file named T35, respond to “C--” by
typing “%ASG,T T35,F2”.
When command mode is entered at trace termination, the trace may be completed only
by using the GO or STEP commands or a command with an equivalent effect. Once
such a command is entered, no further commands are executed, and the trace
terminates. The activity then continues execution or exits, depending on the type of
trace termination.
In all cases where number is called for, octal notation is assumed. Unless indicated
otherwise, a leading zero is not required. In general, SNOOPY uses octal notation
everywhere except in register designations and in the instruction cycle count printed by
SNOOPY.
Certain commands (TOFF$, EXIT$, and CHANGE) clear SNOOPY's command buffer
before reading further commands because of the potentially irreversible nature of the
operation that will be performed. If this is not desired, affix an asterisk to the command
(TOFF*). For example, to terminate a trace and continue an execution without typing in
two lines, use the sequence “TOFF$*GO”.
Refer to 24.4.2 for a list of all SNOOPY commands. All commands except ALTPRT,
TON$, RBK, RLIB, and STEP can be abbreviated to the first character.
In some cases, particularly for complex programs, the set of commands SNOOPY
provides may not meet all debugging requirements. For this reason, there is a method
that allows the command interpreter to be extended as needed.
24–6 7833 1733–004

Program Trace Routine
SNOOPY links to a user-supplied subroutine when it encounters a command that is not
contained in the set of standard commands. (Because one-character abbreviations are
permitted for most SNOOPY commands, the command cannot begin with the same
letter as a SNOOPY command. Therefore, the commands should begin with a $
character.)
A user command routine is identified to SNOOPY by storing its address in H2 of the
externally defined cell SNUCM$. If SNOOPY cannot recognize the command, the user
routine must return to 0,X11; normal return is to 1,X11. The volatile register set can be
used without saving and restoring it.
When SNOOPY enters the user command routine, registers A1 and A2 contain the
command in Fieldata, the command is left-justified and space-filled, register X2 contains
the current program address (simulated P register), and X10 points to an area containing
the program's simulated control registers. These registers are located offset to a
location that corresponds to their absolute addresses; for example, A0 contents at
014,X10, R5 contents at 0105,X10, and so on. The program can change the value in
SNUCM$ at any time, even while SNOOPY is performing a trace. If it is set to zero,
SNOOPY does not interpret any user commands.
The command routine may reference SNOOPY's command reading routine and lexical
scanner by performing an SLJ to SNGTC$. A0 should contain zero or a pointer to a
TREAD$ packet before it calls SNGTC$.
If register A0 = 0, SNOOPY will not read the input; the remainder of the line containing
the user command will be scanned for information. If A0 contains a TREAD$ packet
pointer, the calling program must specify the input buffer SNBUF$. On return from
SNGTC$, register A0 is unchanged; A1 and A2 contain a Fieldata command which is
left-justified and space-filled (unless A3 = 0); A3 contains the nonblank character count
for A1 and A2; and register R1 has the terminated delimiter. If an entirely blank line is
encountered, registers A3 = 0 and R1 = '/'.
SNOOPY commands conform to element name syntax (alphabetics, numerics, “-”,
and “$”).
24.4.1. Contingency Processing
In some cases, because of time constraints, it is undesirable to use SNOOPY to trace an
entire program. Instead, SNOOPY can gain control only when a contingency occurs.
To call a routine that does this, enter the following:
SLJ SNCNT$
After this calling sequence is read, the program proceeds normally until a contingency is
encountered. When a contingency occurs, SNOOPY takes control and the simulated
P register points to the contingency address + 1. A message indicating the nature of the
error is printed. If the contingency is fatal and the program is in batch mode, SNOOPY
exits (EXIT$). For nonfatal contingencies, the remainder of the program is executed.
7833 1733–004 24–7

Program Trace Routine
In demand mode, the caller has control and can examine the program environment. No
distinction is made between fatal and nonfatal contingencies in demand mode. Note
that it is the caller's responsibility to clear registers in case of arithmetic fault and to
respond to the onsite operator in case of a II keyin. For interrupt guard mode (IGDM),
the trapped address may or may not be the address of the offending instruction.
Contingency interception can be reset with the following:
SLJ SNCLR$
In frequently executed code, the caller may not want to trace every iteration of a loop or
every call of a subroutine. A bug may not appear until a routine executes a number of
times. The following calling sequence provides a way to call SNOOPY selectively.
SLJ TCNT$
+ count,start
+ until,every
+ mode-bits,termination-address
where mode-bits and termination-address are the same as for an SLJ to SNOOPY.
The count field should be zero initially; it is incremented on each pass through the code.
If start ≤ count < until and (count - start)///every = 0 or (count - start) modulo every = 0,
SNOOPY begins tracing following the mode word. Otherwise, execution will continue in
normal (untraced) mode.
24.4.2. Demand Mode Commands
These are the SNOOPY commands, their permissible abbreviations, and their functions.
ABSAD (ABS, A)
Converts relative program addresses to absolute addresses. The parameters are
eltname,loc-counter,location.
or
symbol*
If the program is segmented and the specified address is in a segment not in main
storage, a message is printed.
In case of symbols, the Collector may look up only referenced symbols defined by
non-SYS$*RLIB$ routines unless the collection source code includes a
“TYPE EXTDIAG” statement. In this case, the Collector may search for all symbols
(see the Collector Programming Reference Manual).
This command is useful in conjunction with the BREAK, CAPTUR, CHANGE, DUMP,
JUMP, and TRAP commands.
24–8 7833 1733–004

ALTPRT (PRT)
Program Trace Routine
Sends all trace printout to an alternate print file while command solicitation,
command responses (as for DUMP, for example), and all program print requests are
sent to the terminal as usual. One parameter may be entered that is the name of
the file to be used as an alternate print file. If the file specified is not assigned,
SNOOPY automatically assigns a temporary file. (If the file will be printed by the
@SYM statement, it must be assigned as cataloged rather than temporary.) If the
program traced uses alternate symbiont files, the restrictions on the maximum
number of alternate files that are allowed open must be followed.
The ALTPRT command gives control of the alternate print files. In general, the
ALTPRT command uses an alternate file and the current alternate file is breakpointed
(@BRKPT). This action may be suppressed by using an asterisk (*) as the trailing
delimiter for the parameter (for example, either “ALTPRTfilename*” or
“ALTPRT *”).
To obtain printouts both at a terminal and in an alternate file, the ALTPRT filename
should have a trailing exclamation point (!), (for example, “ALTPRTfilename!”). This
is useful for obtaining a permanent record when working at a terminal that lacks a
hard-copy capability. If an alternate file is already active, the command forms
“ALTPRT !” and “ALTPRT ?” may be used to set and clear echo mode while leaving
the same alternate file in use. Echo mode is always cleared when the trailing
exclamation point is not used. Therefore, to start a new alternate file without
breakpointing the old file and with echo mode set, use the command sequence
“ALTPRT* ALTPRTfilename!”.
If the parameter is omitted (as in “ALTPRT/”), printing is directed to the terminal as it
is initially. This command is effective for all SNOOPY operations until another
ALTPRT command is given or the program being traced terminates. This command
forces the location counter element name printout to be given so that each piece of
printout may be easily identified.
BREAK
The BREAK loc-1, loc-2,... command indicates a stopping point for SNOOPY when
operating in trace mode. When any specified address is reached, the trace stops
and SNOOPY enters command mode. This command is useful for running with
printing turned off. Use the form BREAK+ to add entries to the existing table. A
maximum of 16 addresses is permitted. Use the $ specification to retrieve the last
address returned by the ABSAD command. The form BREAK? lists the table of
break addresses. The command BREAK may be abbreviated to just the letter B.
This form of the BREAK command is incompatible with the previous form. The
change is made for reasons of efficiency and utility; the break on element name or
location counter was seldom used but introduced considerable overhead for each
instruction traced, while it was impossible to have more than one break active at the
same time. Determine which form of the BREAK command is available in SNOOPY
by entering the BREAK command without parameters on the same line (or a “/” to
indicate no parameters). The old form of BREAK solicits input with “ELT NAME--”,
whereas the new form requests input with “LOCN--”.
7833 1733–004 24–9

Program Trace Routine
CAPTUR
Enters SNOOPY from ordinary program execution mode whenever control reaches
any of a specified set of addresses. The instructions at the specified addresses are
overlaid by a jump to a SNOOPY internal table area, where an SLJ TON$ is
performed, followed by the overlaid instruction. The overlaid instruction may not be
referenced as data by the program, but there are no other restrictions. The syntax of
the command is CAPTUR loc-1,loc-2,..… Up to eight locations may be specified,
separated by commas. Any existing list is replaced by the new list (with the overlaid
instructions restored). If CAPTUR+ is used, the specifications are added to the
existing table, again up to a total limit of eight. Use CAPTUR? to print out the
contents of the table.
When using this command with segmented or multibanked programs, take care that
the specified capture locations are in main storage when they are changed. The
locations must not reside in a read-only bank. The purpose of this command is to
provide the fastest possible means of getting past a portion of the program that is
irrelevant to the debugging task. The use of external symbols is subject to the
restrictions noted for the ABSAD command. See CHANGE command for use of the
symbol $.
CHANGE (C)
Allows the caller to change the contents of control registers or main storage. The
single parameter specifies the location to be changed. After reading the location
parameter, the contents of the specified location are displayed as if the location
parameter had been given to a DUMP command; then the new value is solicited.
The new value is stored and the new contents displayed. A void new value does not
change the indicated main storage element.
If the parameter is a register name, a number, or a number or register name
preceded by an H or Q, the new value is to be entered as a single octal number.
The CHANGE command allows the caller to use mnemonics and external symbols
for I format (instruction format) changes, as well as octal values. The first item given
to “NEW VAL--” may be an op-code mnemonic instead of an octal number for the
f-field of the instruction. Abbreviated forms such as L, LN, ANM, etc. are not
permitted; however, LX, LA, LR, LNA, ANMA, and so on must be used.
For some instructions, the op-code mnemonic specifies values for the j-field and
perhaps the a-field as well. In such cases, the next value given to the CHANGE
command is an a-field or an x-field. Mnemonics may also be used for the
j-designator values (W, H1, H2, XH1, XH2, T1, T2, T3, S1, S2, S3, S4, S5, S6, Q1, Q2,
Q3, Q4,U, and XU) and for standard X, A, and R register names. If a register name is
used in the a-field of an instruction, its value will be adjusted appropriately.
Truncation errors are not detected.
24–10 7833 1733–004

Program Trace Routine
Fields of an instruction are always expected to be entered in the order f, j, a, x, h, i,
and u. Note that the h- and i-fields are combined. An external symbol may be used
for any field except the f-field, subject to the same restrictions noted for the ABSAD
command.
For specification of an address to the CHANGE command, $ and $P have the following
special meanings:
$P
$P-n$
P+n
$
$-n$
+n
CLEAR
The P register of the traced program.
Where n is an octal number used to compute a value offset negatively or
positively from $P.
The last value returned by the ABSAD command, or the last address plus one
changed (CHANGE) or dumped (DUMP). This allows the caller to continue a
dump or change operation immediately following the last area referenced, or to
change a cell at an address to be calculated by ABSAD without retyping the
absolute address.
Where n is an octal number, used to compute a value offset negatively or
positively from $.
The form $P (but not $P-n, $, or $-n) may also be used with the RELAD command.
Clears one or more flags. List the flags to be cleared as names separated by
commas. See the STATUS command for flag names and meanings.
DUMP (D)
Displays the program status. Separate each parameter by a comma. If no
parameter or an empty parameter (that is, two consecutive commas) is entered, all
registers and the carry and overflow designators are dumped. The parameters are:
A,X, or R
Dumps the indicated group of registers. To dump the contents of a single
register, use the register mnemonic or the octal address.
7833 1733–004 24–11

Program Trace Routine
T
L
B
S
E
N
Dumps the carry and overflow designators.
Displays current storage limits.
Displays names of active banks (in order main-I, main-D, utility-D, with commas
indicating place for unbased BDR portions) indicate write-inhibited banks by an
asterisk (*). Banks whose names cannot be found in diagnostic tables are
printed in octal numbers.
Displays names of active segments.
Last contingency and address, if any.
Instruction cycle count.
Any dump specification that references an address may be given a trailing + sign
followed by an octal number n. A dump is then taken of n consecutive storage locations
following the original address in the same format as the first dump, resulting in a dump
of n+1 locations. The number of items printed per line depends on the line length set by
the LINE command.
If a specification number is neither the address of a register nor within the storage limits
of the program, an error message is displayed.
See CHANGE command for use of symbols $ and $P.
The contents of the specified location or locations are printed in octal unless a format
letter is given. The format letters are as follows:
• The letter I preceding a number or register designator produces an instruction format
dump.
• The letter H preceding a number or register designator produces a Fieldata character
dump.
• The letter Q preceding a number or register designator produces an ASCII character
dump.
24–12 7833 1733–004

EXIT$ (E)
GO (G)
HDG
JHT
Program Trace Routine
Terminates the traced activity by means of an EXIT$ request. Trace mode is
terminated and the last instruction is printed.
Returns to trace mode from command mode.
This command allows the caller to insert print control information into SNOOPY's
output, whether directed to a standard symbiont file or to an alternate file. Unless
given as “HDG*”, the command buffer is flushed, and all other commands on the
line are ignored. In any case, the input for this command is solicited by the printout
“HDG- -”. Only print control information may go on this line; no commands are
permitted. The format is identical to that used for the PRTCN$/PRTCA$ ERs.
In particular, for heading information, the format is “H,opt,ps,txt”. But any of the
other print control functions may be used.
Prints the jump history table, starting with the most recent jump-from address and
continuing with the last eight jump instructions that transfer control. The table is
cleared on entry to SNOOPY, so fewer than eight addresses may be printed early in
a trace. A jump that has been executed several times in succession without any
other jumps intervening (that is, a loop) produces a listing with a repeat count, rather
than many identical entries in the table. On 1100/60, 1100/70, and 1100/80
systems, if SNOOPY is activated by a contingency after a call on SNCNT$, the JHT
command can be used to retrieve the hardware jump history stack as captured at
the time of the contingency. This applies only to hardware contingencies (IOPR,
IGDM, IFOF, IFUF, and IDOF).
JUMP (J)
Transfers control to an address specified as an octal number or externally defined
symbol. The current absolute and relative P-register values are displayed. If the new
value is within the program storage limits, that value is set into the P register. The
new value is printed in relative form, and the next command is executed.
This command is the only way to get out of EXIT$ mode and do further tracing by
means of the TON$ command. If TON$ is used in the EXIT$ mode without a JUMP
command, the TON$ command is rejected and a message is displayed.
If a JUMP command is used in EXIT$ mode termination, the termination mode
becomes a TOFF$ termination. Use a TON$ command to continue tracing.
The jump-to address specified for the JUMP command may be an external symbol
as well as an octal value, subject to the restrictions on use of external symbols noted
for the ABSAD command.
7833 1733–004 24–13

Program Trace Routine
LINE
Adjusts the length of the line printed by SNOOPY. If "LINE /" is entered, the line
length set is the default value of 132 decimal = 204 octal. Otherwise, the parameter
given to LINE must be an octal number denoting the line length for the device in
use. As indicated, the default value is 132 decimal = 204 octal for devices such as
DCT 500 terminals.
For a UNISCOPE or UTS Display terminal, use “LINE 116” with alternate print files
(see the ALTPRT command), “LINE 204” may be the most convenient. The effect
of a LINE command is canceled by the next LINE command or by program
termination. The previous value will be printed as “WAS nnn”. This value is also
printed when SNOOPY signs on unless NO HDG is set.
number
Has the same effect as a SKIP n GO sequence (where n is the number). See SKIP
command. The number is in octal.
PRINT (P)
Allows the amount of printing to be modified. The PRINT command recognizes only
one parameter at a time. If an invalid parameter or no parameter is specified, the
F parameter is assumed. The parameters are:
C
E
F
N
P
Produces a printout omitting extraneous formatting spaces.
Produces an expanded printout including formatting spaces. The E mode is
effective until a PRINT C is encountered.
Produces a full printout consisting of each instruction, its location, and the
contents of main storage and registers (in before/after form if the value
changed). For certain Executive Requests, the contents of the associated
packet are also dumped. This is the default mode.
Suppresses printout. This provides a means of skipping long sections of
irrelevant code.
Produces a printout of the instructions but not referenced main storage or
Executive Request packets. If SNOOPY is in the N mode, the P mode is entered
automatically upon the occurrence of an RBK contingency or encountering a
BREAK-specified break condition.
24–14 7833 1733–004

RBK
I,n
M,msk
Program Trace Routine
The value of n is an exponent of 2, indicating the frequency with which the
instruction cycle printout is given. The default is 10, the minimum is 6. Turn off
the printout using a value of 35.
The value of msk is a mask that determines which instructions are to be edited
while tracing. The most useful value for msk is 400, which suppresses all
instructions except for jumps, skips, and Executive Requests. Other values for
msk are determined by examining the code for SNOOPY (edit descriptor bits).
Allows the caller to simulate an RBK contingency for the executing program; the
actual RBK contingency is intercepted by SNOOPY and directs a return to command
mode. This command allows a contingency routine to be traced. If the program
does not expect the contingency, an appropriate message is displayed.
RELAD (R)
Converts absolute program addresses to relative addresses. A list of locations
separated by commas may be specified as parameters.
See $P specification for DUMP command.
Ambiguities are resolved in favor of elements residing in loaded segments in active
banks; otherwise a location may be specified as addr/bdi.
RLIB param
param may be an A, E, L, N, or X. Anything else is assumed to be N. The
parameters are:
A
Allows tracing of RLIB$ routines, which include elements from the SYS$*RLIB$
and SYS$*DATA$.LIB$NAMES files and elements marked as being from the
files by the Collector RLIB directive.
E,element-list
Where element-list is a list of element names separated by commas specifying
that the elements named should be treated as if they were RLIB$ elements for
the purposes of RLIB$ trace suppression. The specified list completely replaces
any preceding list. If a “+” sign follows the E, the listed elements are added to
the current list. A maximum of 16 names can be specified. An empty list is
specified by following the “E” with punctuation other than a comma, a plus sign,
or a question mark. “RLIB E?” prints the current list.
7833 1733–004 24–15

Program Trace Routine
SET
L
N
Prints the system type, system level identification, and site as well as the RLIB$
level used at collection time.
Suppresses trace printout of RLIB$ code and common banks. When tracing of
RLIB$ is suppressed (which is the default mode for demand operations), an
RLIB$ code is entered. The print mode is in effect saved. Printing is then
turned off, and the RLIB$ code is interpreted until control leaves RLIB$ code. At
this time, the print mode is restored and normal execution continues. This
command may be used at any time. If it is used to change the mode while the
program is in RLIB$ code, the effect will be as if RLIB$ was just exited (from N
to A) or entered (from A to N). This means that the print mode will be saved or
restored, respectively.
X,element-list
Has syntax identical to that for "RLIB E", but the effect is inverted. That is, any
element not contained in the RLIB X list will be treated as an RLIB$ element.
Use RLIB X+ to extend the line.
If a break interrupt happens to give control in RLIB$ (or pseudo-RLIB$) code and
RLIB$ tracing is suppressed, the STEP command and the blank line command are
disabled. This prevents losing control when a blank line is transmitted by the break
contingency under certain EXEC levels. Be sure to turn off printing or else allow
RLIB$ tracing so that a runaway print can be avoided.
Sets one or more flags. List the flags by name. The names must be separated by
commas. See the STATUS command for flag names and meanings.
SKIP n (S)
Returns to command mode after executing n number of instruction cycles. If n is
omitted, any previously existing skip count is deleted and no skip interrupt occurs.
Otherwise, an octal number is used to set the interrupt point. If the count is
exceeded during an indirect addressing or execute remote cascade, the command
mode is reentered when the instruction is completed.
24–16 7833 1733–004

STATUS
Program Trace Routine
Prints the status of any or all flags. Use the STATUS? command to print all flags.
Otherwise, these flags may be listed, separated by commas. The flags are as
follows:
STEP n
Name Action If Set
BYPADD Bypasses @ADD images when looking for a SNOOPY command.
NOHDG SNOOPY sign-on and sign-off information is suppressed.
UXUCOR The u-field is looked up in SYMTB$ for J = U (016) or XU (017) when
the x-field is zero.
Executes n instructions in trace mode and returns to command mode. Default for n
is one.
TOFF$ (T)
TON$
TRAP
Leaves the trace mode and continues execution as if an SLJ TOFF$ command had
been executed. Trace mode is then terminated, and the last instruction is printed.
Restarts a trace that will be terminated and executes one instruction. To compute
the number of instruction cycles performed, use the TOFF$ command followed by
the TON$ command. The TON$ command is not affected if the activity is about to
terminate by means of an EXIT$ request; to continue tracing from that point, use a
JUMP command to first establish a point from which execution will continue.
Enters command mode from trace mode whenever one of a set of locations is
referenced or altered except for ER operations. The locations may be octal numbers,
register mnemonics, or external symbols. Entering the command
“TRAPloc-1,loc-2...” places up to 16 locations in the trap table for the locators. Use
commas as separators.
If an asterisk immediately follows “TRAP”, the trap occurs only when a location's
contents are changed. If the change occurs by using an Executive Request or
asynchronously, the trap occurs at the next reference. If an exclamation point
immediately follows “TRAP”, the trace does not stop when a trapped location
changes. The old and new values are displayed, even in “PRINT N” mode.
The use of external symbols is subject to the restrictions noted for the ABSAD
command. Each specified list completely replaces the preceding list unless TRAP is
followed immediately with a + (intervening spaces not allowed). In this case, the
specifications are added to the list. The command “TRAP?” prints out the current
list. See CHANGE command for use of the symbol $.
7833 1733–004 24–17

Program Trace Routine
24.5. Control Flags
The location of some of SNOOPY's control flags is externalized with the label SNFLG$.
In addition, the system procedure SN$DEF provides mnemonic tags for the following
flags:
BYPADD
CCALL
Set to bypass from @ADD streams when reading a SNOOPY command.
(SNFLG$+2,,S2)
Set by SNCNT$, cleared by SNCLR$. (SNFLG$,,S2)
CMODE
Set when tracing a contingency routine. (SNFLG$+1,,S2)
COMPRT
Set for compressed print ("PRINT C"), clear for expanded print. (SNFLG$+1,,S3)
CONTINGF
ECHO
Set when a contingency has occurred, otherwise clear. (SNFLG$,,S5)
Set for echo mode of ALTPRT. (SNFLG$+1,,S6)
NOHDG
Suppresses SNOOPY sign-on and sign-off messages. (SNFLG$+2,,S4)
OLDSKP
Saved value of REMSKPIT when RLIB$T = 0 and WASRLB = 1. (SNFLG$+1,,S5)
REMBRK
Set when the break contingency has occurred or by encountering a condition set by
the SKIP (or number) command, the BREAK command, or the TRAP command.
When set, SNOOPY enters command mode before interpreting the next instruction.
(SNFLG$,,S6)
REMOTE
Clear for batch mode, set for demand mode. (SNFLG$,,S1)
24–18 7833 1733–004

REMPRT
Program Trace Routine
Set for partial-print mode ("PRINT P"), clear for full-print mode. (SNFLG$,,S3)
REMSKPIT
RLIBX
Set for suppress print mode ("PRINT N"), clear for full- or partial-print mode.
(SNFLG$,,S4)
RLIB$T
Set if RLIB list is in exception mode, otherwise clear. (SNFLG$+2,,S1)
Set to enable RLIB$ tracing ("RLIB A"), clear to suppress RLIB$ tracing (“RLIB N”).
(SNFLG$+1,,S4)
UXUCOR
Set to look up u-fields in SYMTB$ when x-field is zero and j-field is U (016) or
XU (017). (SNFLG$+2,,S3)
WASRLB
Set when executing an RLIB$ or pseudo-RLIB$ element. (SNFLG$+1,,S1).
7833 1733–004 24–19

Program Trace Routine
24–20 7833 1733–004

Section 25
SOR–Symbolic Output Routine
The Symbolic Output Routine (SOR) writes symbolic images produced by a processor
into a program file as a symbolic element. The symbolic element produced by SOR is
suitable for input to another processor by SIR$.
The symbolic output produced by SOR should not be confused with the symbolic output
produced by SIR$, described in Section 23. The symbolic output produced by SIR$ is
based on the source input (SI) file or element, as modified by optional runstream
corrections. The symbolic output produced by SOR is independent of the SIR$ symbolic
output and is completely under control of the calling processor. SOR would normally be
used by a processor that produces symbolic output rather than relocatable, omnibus,
absolute, or object module output.
The calling program must supply a 40-word PARTBL that is zero filled. The name
PARTBL must be externally defined. See Figure 14–1 for PARTBL description. For
symbolic output, SOR uses words 27 through 39 of PARTBL, the table item normally
used for relocatable output.
The calling program must insert the following information in PARTBL before calling SOR.
The PREPRO routine can be used to enter the information from the second field
(relocatable output) of the processor call statement to PARTBL.
PARTBL+27,+28 Internal file name
PARTBL+29,+30 Element name
PARTBL+33,+34 Version name
7833 1733–004 25–1

SOR–Symbolic Output Routine
SOR inserts the following:
S2 of PARTBL+32 Bit 7, the ASCII bit, is zero if the first symbolic image written by
SOR is Fieldata; otherwise, the ASCII bit is set to 1.
S3 of PARTBL+32 Element type is set to (01-symbolic).
T1 of PARTBL+35 Cycle limit is set to the system standard (CYCLIM$).
T2 of PARTBL+35 Latest cycle number is set to zero.
T3 of PARTBL+35 Current number of cycles is set to 1.
S1 of PARTBL+36 Element subtype is set to 01 (ELT).
H2 of PARTBL+36 Length of text.
PARTBL+37 Location of text.
PARTBL+38 Time and date element created. Initialized to zero by SSOR$
routine. User may insert time and date after SSOR$ call;
otherwise, current time and date will be used.
PARTBL+39 Next write location in program file.
25.1. SSOR$–Start Symbolic Output
SSOR$ initializes the SOR routine by setting up the appropriate PARTBL fields and by
opening the System Data Format Output (SDFO) routine.
Calling Sequence
LMJ X11,SSOR$
error return
normal return
SSOR$ initializes and makes PARTBL entries for a symbolic element. If the calling
program also calls SIR$ and if the same file is used for both SIR$ source output and SOR
symbolic output, then SSOR$ should not be called until SIR$ has created its source
output, which occurs at the end of the first pass through SIR$. This is necessary
because the text location for SOR symbolic output cannot be correctly determined using
ER PFWL$ until SIR$ has created its source output element. The SDFO packet with the
external label SORFCT$ is opened for SOR symbolic output.
The calling program receives control at the error return if ER PFWL$ encounters an error
condition. (See the Exec ER Programming Reference Manual) On an error return,
register A2 is nonzero, and contains the ER PFWL$ status.
25–2 7833 1733–004

SOR–Symbolic Output Routine
25.2. SORASC$ and SORASCA$–Output ASCII
Image
The SORASC$ and SORASCA$ routines write an ASCII image from a location specified
by the calling program to the symbolic output element.
Calling Sequence
L A0,(image-length,image-location)
LMJ X11,SORASC$ (or SORASCA$)
error return
normal return
where:
image-length
The length in words of the symbolic image to output.
image-location
The address of the symbolic image to output.
If this is the first call to output an image, SOR calls SDFO to write the SDF Label control
record. If the SORASC$ entry point is called, SOR checks for and suppresses words of
ASCII spaces at the end of the image. If the SORASCA$ entry point is called, there is no
space suppression and image-length words are written. SOR calls SDFO to write the
symbolic image.
The following are the causes of SOR error returns:
• If the image-location is zero but the image-length is nonzero, SOR returns with A5
zero.
• If an unrecoverable SDFO I/O error is encountered, SOR returns with A5 containing
the nonzero I/O error status code.
• If the image-length is over the maximum of 2,047 words, SOR returns with A5
containing the illegal word count.
7833 1733–004 25–3

SOR–Symbolic Output Routine
25.3. Output Fieldata Image
The SOR$ and SORA$ routines translate into ASCII a Fieldata image from a location
specified by the calling program and write it to the symbolic output element.
Calling Sequence
L A0,(image-length,image-location)
LMJ X11,SOR$ (or SORA$)
error return
normal return
where:
image-length
The length in words of the symbolic image to output.
image-location
The address of the symbolic image to output.
If this is the first call to output an image, SOR calls SDFO to write the SDF Label control
record. If the SOR$ entry point is called, SOR checks for and suppresses words of
Fieldata spaces at the end of the image. If the SORA$ entry point is called, there is no
space suppression. If this is the first call to SOR$ or SORA$, SOR prints the following
informational message:
SOR: Fieldata symbolic output in not allowed; output is in ASCII.
SOR then translates the Fieldata image to ASCII. The buffer that SOR uses for the
translation is 63 words long, so if the Fieldata image is 42 words or less, SOR translates
the image and then calls SDFO to write it. If the Fieldata image is more than 42 words,
the entire image cannot be translated and written at once. In this case, SOR calls SDFO
to write the first 63 words of the translated image; then continues by translating the next
part of the Fieldata image and calling SDFO to write it as an SDF Continuation control
record, octal code 051. SOR continues writing Continuation control records until the
entire Fieldata image has been translated and written.
To write a Fieldata image to the symbolic output element in Fieldata, the calling program
can use the SORNM$ or SORNMA$ calls described in 25.4. Note also that SOR can be
configured so that the SOR$ and SORA$ entry points write Fieldata images with no
translation to ASCII.
The SOR error returns described for SORASC$ and SORASCA$ in 25.2 also apply to
SOR$ and SORA$.
25–4 7833 1733–004

SOR–Symbolic Output Routine
25.4. SORNM$ and SORNMA$–Output Specified
Coded Character Set Image
The SORNM$ and SORNMA$ routines write, without translation, an image from a
location specified by the calling program to the symbolic output element. The coded
character set (CCS) of the image is specified by the calling program.
Calling Sequence
L A0,(image-length,image-location)
L,U A1,CCS-identifier
LMJ X11,SORNM$ (or SORNMA$)
error return
normal return
where:
image-length
The length in words of the symbolic image to output.
image-location
The address of the symbolic image to output.
CCS-identifier
The CCS of the symbolic image, as described in Table I–1. The calling program is
responsible for assuring that the symbolic image has the correct format for the
specified CCS. Note that CCS octal 076 is reserved for future use and is currently
illegal.
If this is the first call to output an image, SOR calls SDFO to write the SDF Label control
record. If this is not the first call to output an image, SOR checks if the CCS identifier for
the image to be written is the same as the CCS of the previous symbolic image. If it is
not, SOR calls SDFO to write a Character Set Change control record, octal code 042.
This control record indicates the CCS of one or more symbolic images that follow.
The SORNM$ entry point is called to request space suppression at the end of the image.
If this is a Fieldata image (CCS 0), SOR checks for and suppresses words of Fieldata
spaces. If this is an ASCII image (CCS 1) or an image in one of the 39 CCSs listed in
Table I–1 as “ASCII-like,” SOR checks for and suppresses words of ASCII spaces. If this
is an image in one of the 22 CCSs that is not Fieldata, ASCII, or ASCII-like, SOR checks
for and suppresses words of binary zeroes. If the SORNMA$ entry point is called, there
is no space suppression.
The SOR error returns described for SORASC$ and SORASCA$ in 25.2 also apply to
SORNM$ and SORNMA$. The following error return is unique for SORNM$ and
SORNMA$: If the CCS-identifier is not a legal CCS (A1 is negative, equal to octal 076 or
over octal 077), SOR returns with A5 (H1) equal to 1 to indicate a CCS identifier error and
A5 (H2) equal to the CCS identifier.
7833 1733–004 25–5

SOR–Symbolic Output Routine
25.5. ESOR$–End Symbolic Output
ESOR$ terminates the operations of the SOR routine.
Calling Sequence
LMJ X11,ESOR$
error return
normal return
ESOR$ terminates SOR, closes SDFO, and inserts the generated element in the
program file (ER PFI$). If SOR takes the error return from ER PFI$, register A5 equals
zero; register A2 contains the descriptive code. If the error return is from SDFO, an
(unrecoverable) I/O error occurred and register A5 contains the I/O status code.
25.6. SOR File Control Table (SORFCT$)
The file control table (FCT) and the buffers provided by SOR for SDFO are similar to
those SDFI requires. Therefore, the external label SORFCT$ is provided for the first
word of the FCT.
Although SORFCT$ is initially zero, it is set to nonzero when SSOR$ is called; SORFCT$
is reset to zero when ESOR$ is called. If SORFCT$ is nonzero when SSOR$ is called, a
01 (no find) error condition is returned in register A2. If the calling program uses the FCT
and SOR buffers, it must do the following:
• Check that SORFCT$ is zero before using it.
• Set SORFCT$ to zero while using it.
• Reset SORFCT$ to zero when it is no longer required.
• Be sure S2 of SORFCT$+3 is the correct I/O code.
Note: SIR$ has its own input FCT and buffers for SDFI use.
25–6 7833 1733–004

Appendix A
Using SYSLIB
This appendix contains suggestions for using SYSLIB.
A.1. Efficient Collections
Under certain conditions, the efficiency of the Collector can be improved when using
SYSLIB relocatable elements. These conditions are:
• SYSLIB has been installed with COMUS level 4R2 or higher.
• The Exec level is 40R1 or higher.
• The Collector level is 31R2 or higher.
• The SYSLIB elements are not explicitly included with the “IN file-name.elementname”
directive.
If these conditions are met, programs that call SYSLIB routines should use the MASM
INFO 12 directive. This directive instructs the Collector to search the library file
SYS$LIB$*SYSLIB before searching other library files. The format of the INFO 12
directive is
$INFO 12 'SYSLIB'
where ‘SYSLIB’ is the keyword for the SYS$LIB$*SYSLIB file. For details, see the
MASM Programming Reference Manual.
A.2. PLUS Routines
When any SYSLIB routines written in PLUS are used, the PLUS library must be available
when collecting programs. SAR$ is the only SYSLIB routine that is currently written in
PLUS. If PLUS is installed with COMUS or is included in the SYS$RLIB$ file, the
Collector will automatically include referenced PLUS elements. IF PLUS is installed in a
different file, it may be necessary to use the Collector LIB directive of MAP$PF use
name. See the Collector Programming Reference Manual for more information on the
Collector LIB.
A.3. Compilations
Attach MASM$PF or PLS$PF to file SYS$LIB$*SYSLIB, or the file containing SYSLIB,
and assign it to the run. This will decrease the assembly and compilation time. Use the
M option with PLS.
7833 1733–004 A–1

Using SYSLIB
A–2 7833 1733–004

Appendix B
Diagnostic Messages
This appendix contains processor interface routine messages and SIR$ line-change
diagnostics.
B.1. Processor Interface Routine Messages
In the following messages, x may be either si, ro, or so, corresponding to the parameters
on the processor call statement.
The following messages are produced by the Processor Interface Routines:
ABNORMAL RETURN FROM READ$
A program which expects to be called as a processor has been called with @XQT.
x BADLY CODED FIELD
Fill from previous parameter was requested, and the filled parameter is illegal or
ambiguous.
x CYCLE SPECIFICATION IGNORED
ro and so cycle specification is meaningless and is ignored. Does not cause error
return.
x FILE CANNOT BE READ
Input file is in read-inhibited mode due to absence of read-key, write-only mode is
set for file, or Y option is used on the file assignment.
x FILE ERROR WAS REPORTED BY ER z - STATUS IN A2 = n
Error status was received when acquiring file information using an OS 2200 program
file package (PFP) request. z is the mnemonic of the ER and n is the PFP status
code. See the Exec ER Programming Reference Manual.
x FILE IS TAPE
ro and so may not specify tape files.
7833 1733–004 B–1

Diagnostic Messages
x FILE NOT AVAILABLE - STATUS: n
An attempt to assign a file has failed. Status n is the facility request status code.
See the Exec ER Programming Reference Manual.
FILE NOT ASSIGNED: x
POSTPR$ has tried to release (@FREE) a file that was not assigned. The calling
program has probably altered PARTBL.
x ILLEGAL DEVICE
Output file is not sector-formatted or input file is neither tape nor sector-formatted.
x ILLEGAL FIELD
The field is ambiguous with the option given; that is, I option is specified and the
symbolic output parameter is specified.
INVALID SDF LABEL WORD w
An attempt was made to process an invalid SDF file or element. w is the first two
words printed in Fieldata.
I/U OPTION CONFLICT
Both I and U options were given on processor call statement. This situation is
ambiguous.
x NOT A PROGRAM FILE
The file specified may not be used as a program file.
PROCESSOR CALL ERROR
A program which expects to be called as a processor has been called with @XQT.
x READ ONLY OUTPUT FILE
Output file is in a write inhibited mode, due to absence of write-key, read-only mode
set for file, or Y option is used on the file assignments.
SIR$: OUTPUT OF CCS 076 IMAGE NOT ALLOWED
CCS 076 is reserved for future use and is currently illegal. SIR$ does not write
images in this CCS to the source output.
SIR$: OUTPUT OF CCS 0nn IMAGE REQUIRES ‘P’ AND ‘Q’ OPTIONS
Octal CCS 0nn is not Fieldata, ASCII, or ASCII-like. SIR$ only writes images in this
CCS if both the P and the Q options are either assumed or explicitly included on the
processor call.
B–2 7833 1733–004

SIR$: RETURN OF CCS 076 IMAGE NOT ALLOWED
Diagnostic Messages
CCS 076 is reserved for future use and is currently illegal. SIR$ does not pass
images in this CCS to the calling program.
SIR$: RETURN OF CCS 0nn IMAGE REQUIRES SPECIAL SIR$ INITIALIZATION
SIR$ must be initialized using the INISR$ entry point with A4 bit 2 set to 1 in order to
return images in octal CCS 0nn.
SIR$: RETURN OF CCS 0nn IMAGE REQUIRES SPECIAL SIR$ INITIALIZATION AND USE
OF GETNM$
SIR$ must be initialized using the INISR$ entry point with A4 bit 2 set to 1 and the
calling program must use the GETNM$ entry point in order to return images in octal
CCS 0nn.
SIR$: RETURN OF CCS 0nn IMAGE REQUIRES USE OF GETNM$
The calling program must use the GETNM$ entry point to return images in octal CCS
0nn.
SI: CYCLE NONEXISTENT OR IN ERROR
Requested cycle of specified element does not exist or cycle field has improper
format.
SI: ELEMENT NOT FOUND
Element name given cannot be found as a symbolic element in the specified
program file.
SI: IMPROPER LABEL BLOCK
Symbolic input file is tape, and tape is not positioned at the label block for requested
element, probably because an @FIND has not been performed.
SI IS NOT SIR TYPE SDF
The SDF type is not S (general symbolic) or unspecified; therefore the input element
is assumed to contain no valid cycle information.
SI: MISSING FIELD
A field of required information (for example, element name) was not given.
SI: TAPE I/O ERROR — STATUS: n
Symbolic input file is tape, and I/O status is n.
7833 1733–004 B–3

Diagnostic Messages
SIR EDIT ERR c l
c indicates the cause of the error, and l represents the line number of the last image
retrieved from the input symbolic before the error occurred or before the change
statement in error.
TOO MANY SPECIFICATIONS
A processor call statement is too complex.
B.2. SIR$–Line-Change Diagnostics
When an error occurs, SIR$ passes a print control word in control register A0 back to the
calling processor. Normally the processor performs an ER PRINT$ to inform the caller of
the error. No other image is returned to the processor on an error return. The formats
of the error messages are:
Format 1
SIR EDIT ERR c l
Format 2
c l
where:
c
l
Indicates the cause of the error. Table B–1 lists the possible errors.
Is the line number of the last image retrieved from the input symbolic before the
error occurred or before the change statement in error.
Format 1 is returned when a partial-line-change editing statement is in error. Format 2 is
returned when a line-change or partial- line-change statement is in error.
SIR$ does not make assumptions as to the format of a changed line. Information in
fixed fields—for example, sequence numbers in columns 73 through 80—may be
destroyed when using partial-line-changes, especially formats 2 and 4.
B–4 7833 1733–004

Table B–1. SIR$: Line-change Diagnostics
Error Description
ASCII OUTPUT TRUNCATED Overflow occurred on Fieldata to ASCII translation.
Diagnostic Messages
CARD COUNT < Not enough editing statements were provided. Those lines
for which no editing statement was provided remain
unchanged.
CARD COUNT > Too many editing statements were provided. The excess
editing statements are ignored.
COLUMN The column number specified in Format 1 or 2 editing
statement is out of range or c > d for a Format 2 editing
statement.
COMPRESSED SYMBOLIC
FORMAT ERROR
EDIT OF CCS 0nn
IMAGE NOT ALLOWED
EDITING STATEMENT IN
CCS 0nn NOT ALLOWED
NO CARDS FOLLOW -n No change lines follow -n.
A compressed symbolic image exceeded the maximum
image length when expanded. The remainder of the input
image is ignored.
A source input line referenced by a partial line change
statement is in octal CCS 0nn, which is not Fieldata, ASCII,
or ASCII-like and cannot be edited.
A partial line change editing statement is in octal CCS 0nn,
which is not Fieldata, ASCII, or ASCII-like as required.
NO FIND The characters given in the old-data parameter of a format 3
or 4 editing statement could not be found in the line being
changed.
Whenever a NO FIND, SEPARATOR, or COLUMN error
occurs, the editing statement is ignored and the line remains
unchanged except format -n, where the last changed image
is returned.
OUT OF SEQ The line-change or partial-line-change statement is illegal.
PREMATURE @EOF An end of file encountered when reading compressed
symbolic images. An image has probably been lost.
SEPARATOR The separator used in the editing statement is invalid or
nonexistent.
SI ENDS AT LINE NUMBER n The line-change or partial-line-change references a line after
the last line of the input symbolic. Line number n is the last
line of the symbolic.
7833 1733–004 B–5

Diagnostic Messages
B–6 7833 1733–004

Appendix C
SYSLIB Restrictions
This appendix explains the restrictions of using SYSLIB.
C.1. ASM Compatibility
SYSLIB levels 75R2 and higher are not compatible with OS 2200 Assembler (ASM) level
15R1. ASM routines that use PROCs from SYSLIB levels 75R2 or higher may or may not
assemble correctly with ASM. If they do not, the routines should be assembled with
MASM (any supported level).
C.2. Object Modules
The only elements released in SYSLIB as object modules are ERU$ and SYS$DEF. All
other SYSLIB elements cannot be used as object modules. However, the subset of
SYSLIB routines in the SYSLIB common banks can be accessed from object modules.
SLIB provides equivalent services for the extended mode environment.
C.3. SDFI and SDFO Tape Handling
SDFI and SDFO are not compatible with PCIOS levels 4R1 and 4R1A when handling
multireel tape files.
When SDFI reads multireel tape files created by PCIOS, I/O error 01 (unlabeled tape) or
ER TLBL$ error 013 (labeled tape) occurs. When PCIOS reads multireel tape files
created by SDFO, unlabeled tapes are read correctly, but labeled tapes encounter I/O
error 01.
C.4. Symbolic Access Routine (SAR$)
SAR$ does not process data that is made up only of JIS-16 (kanji) characters. But SAR$
does process kanji characters when they are part of ASCII/ISO shift-coded data and
attributed character data (ACD).
C.5. 65K Addressing Limit
The elements PREPF$, POSTPR$, PREPRM, PREPRO, ROR, and SOR cause truncation
errors during collection if they are located above 65K in the D-bank.
7833 1733–004 C–1

SYSLIB Restrictions
C–2 7833 1733–004

Appendix D
SYSLIB Elements
This appendix contains a complete list of all SYSLIB elements.
The SYSLIB elements are listed alphabetically in Table D–1, along with the element type,
common bank it resides in, and element size. The name of the common bank absolute
is listed if the element is contained in a SYSLIB common bank. The approximate
element size in words is listed if the element is a relocatable element (rounded to the
nearest 0100). All size values are in octal.
Table D–1. SYSLIB Elements
Element Name Element Type Common Bank Size
AEDIT$ Relocatable SYSLIB$1 0400
AEDIT$F Relocatable SYSLIB$1 0500
AEDIT$P Assembler Procedure
AEDIT$SFDT Relocatable SYSLIB$1 0300
AEDIT$T Relocatable SYSLIB$1 0200
AXR$ Assembler Procedure
A$ACD2INT Relocatable SYSLIB$3 0700
A$INT2ACD Relocatable SYSLIB$4 01000
A$INT2SC Relocatable SYSLIB$4 0600
A$SC2INT Relocatable SYSLIB$3 0300
BSP$ Relocatable SYSLIB$1 02500
BUF$TRANS Omnibus
CABSAD$ Relocatable SYSLIB$1 0500
CBEPFORV$ Relocatable 0
CBEPMDP$ Relocatable 0
CBEPUTS4$ Relocatable 0
CBEP$$DMS Relocatable 0
CBEP$$EMSLIB Omnibus
CBEP$$MS Relocatable 0
CBEP$$PIRCB$ Relocatable 0
7833 1733–004 D–1

SYSLIB Elements
Table D–1. SYSLIB Elements
Element Name Element Type Common Bank Size
CBEP$$SYSLIB Relocatable 0
CB$CONFIG Omnibus
CB$RETURNS Relocatable 0
CERU$ Relocatable 0
CERU$ Symbolic
CONWRD$ Relocatable SYSLIB$1 0100
CRELAD$ Relocatable SYSLIB$1 0500
DLOAD$ Relocatable 0100
EDIT$ Relocatable 0400
EDIT$F Relocatable 0500
EDIT$P Assembler procedure
EDIT$T Relocatable 0200
EM$BSP$ICPT Relocatable SYSLIB$1 0200
EM$EDIT$ICPT Relocatable SYSLIB$1 0100
EM$ERS Relocatable SYSLIB$1 0100
EM$FDA$ICPT Relocatable SYSLIB$3 0100
EM$INF$ICPT Relocatable SYSLIB$1 0100
EM$MFD$ICPT Relocatable SYSLIB$2 0100
EM$PSF$ICPT Relocatable SYSLIB$1 0100
EM2CB$P Omnibus
ERU$ Absolute (Object Module)
ERU$ Omnibus
ERU$ Relocatable 0
ERU$ Symbolic
ER$APRTCN$WD Omnibus
ER$APRTCN$WI Omnibus
ER$BRKPT Omnibus
ER$COM$ Omnibus
FDASC$ Relocatable SYSLIB$3 0200
FDASC$PKTD Symbolic
GETPSF$ Relocatable SYSLIB$1 0100
IDLAD$ Relocatable 0100
D–2 7833 1733–004

Table D–1. SYSLIB Elements
Element Name Element Type Common Bank Size
IDLA$ Relocatable 0100
IDLD$ Relocatable 0100
IDLINE$ Relocatable 0200
IDL$ Relocatable 0100
IDONLY$ Relocatable 0100
ID$ Relocatable SYSLIB$1 0400
INFOR$ Relocatable SYSLIB$1 0400
MAXR$ Omnibus
MFDSP$ Relocatable SYSLIB$2 01700
OM$DEF Omnibus
PIRCB$INTCPT Relocatable 0200
PLSG$ID$ Relocatable 0100
PLSG$SFDT$ Relocatable 0100
PLS$ER$PFI$ Relocatable SYSLIB$4 0100
PLS$FDASC$ Relocatable SYSLIB$3 0100
PLS$ID$ Relocatable 0100
PLS$SDFI Relocatable SYSLIB$3 0200
PLS$SDFO Relocatable SYSLIB$4 0200
PLS$SFDT$ Relocatable 0100
PLS$SYMB$ Relocatable SYSLIB$3 0100
POSTPR$ Relocatable 0100
PREPF$ Relocatable 0500
PREPRM Relocatable 01300
PREPRO Relocatable 01400
PROC$ Assembler procedure
ROR Relocatable 0700
SAR$ATREAD$G Relocatable SYSLIB$3 0700
SAR$ATRPKTD Symbolic
SAR$ATR$DG Symbolic
SAR$COMPKTD Symbolic
SAR$COM$DG Symbolic
SAR$COM$G Relocatable SYSLIB$3 0400
SYSLIB Elements
7833 1733–004 D–3

SYSLIB Elements
Table D–1. SYSLIB Elements
Element Name Element Type Common Bank Size
SAR$DEFN Symbolic
SAR$FILEPKTD Symbolic
SAR$PROCS Assembler procedure
SAR$READ$DG Symbolic
SAR$READ$G Relocatable SYSLIB$3 02300
SAR$RPKTD Symbolic
SAR$WPKTD Symbolic
SAR$WRITE$DG Symbolic
SAR$WRITE$G Relocatable SYSLIB$4 03400
SDFI Relocatable SYSLIB$3 0500
SDFI$PKTD Symbolic
SDFO Relocatable SYSLIB$4 0400
SDFO$PKTD Symbolic
SDFP$ Omnibus
SFDTBL$ Relocatable SYSLIB$1 0100
SFDT$ Relocatable SYSLIB$1 0400
SFDT$D Symbolic
SIR$ Relocatable 04400
SNAP$ Relocatable 0200
SNOOPY Relocatable 011300
SOR Relocatable 0400
SSTYP$ Relocatable 0100
SYMB$PKTD Symbolic
SYSLIB$ID Relocatable 0
SYSLIB$1-EP Relocatable SYSLIB$1 0400
SYSLIB$2-EP Relocatable SYSLIB$2 0100
SYSLIB$3-EP Relocatable SYSLIB$3 0100
SYSLIB$4-EP Relocatable SYSLIB$4 0100
SYS$DEF Absolute (object module)
SYS$DEF Omnibus
SYS$DEF Relocatable 0
TABLE$ Relocatable SYSLIB$3 0200
D–4 7833 1733–004

SYSLIB Elements
Table D–2 contains the SYSLIB common bank absolute elements. The table includes the
highest address of the common bank, rounded up to the next 0100. All SYSLIB common
banks begin at address 01000.
Table D–2. SYSLIB Common Bank Absolute Elements
Element Name Element Type Highest Address
PIRCB$ Absolute (common bank) 024000
SYSLIB$1 Absolute (common bank) 011700
SYSLIB$2 Absolute (common bank) 03200
SYSLIB$3 Absolute (common bank) 013300
SYSLIB$4 Absolute (common bank) 011200
7833 1733–004 D–5

SYSLIB Elements
D–6 7833 1733–004

Appendix E
SYSLIB Common Bank Entry Points
This appendix contains a list of all SYSLIB common bank entry points. The common
bank entry points are listed in Table E–1 through Table E–4. They are grouped by the
common bank absolute in which they reside. In each table, the entry points are grouped
by routine, and both the relocatable and common bank entry points are listed.
Table E–1 lists the routines and entry points for SYSLIB common bank SYSLIB$1.
Table E–1. SYSLIB$1 Entry Points
Element Name Relocatable Entry Point Common Bank Entry Point
AEDIT$ AECHAR$ CBAECHAR$
AECLEAR$ CBAECLEAR$
AECOLN$ CBAECOLN$
AECOL$ CBAECOL$
AECOPY$ CBAECOPY$
AEDCFZ$ CBAEDCFZ$
AEDECF$ CBAEDECF$
AEDECV$ CBAEDECV$
AEDITR$ CBAEDITR$
AEDITX$ CBAEDITX$
AEDIT$ CBAEDIT$
AEFD1$ CBAEFD1$
AEFD2$ CBAEFD2$
AEMSGR$ CBAEMSGR$
AEMSG$ CBAEMSG$
AEOCTF$ CBAEOCTF$
AEOCTV$ CBAEOCTV$
AEPACK$ CBAEPACK$
AEPRINT$ CBAEPRINT$
AESKIP$ CBAESKIP$
7833 1733–004 E–1

SYSLIB Common Bank Entry Points
Table E–1. SYSLIB$1 Entry Points
Element Name Relocatable Entry Point Common Bank Entry Point
AEDIT$F AEFLF1$ CBAEFLF1$
AEFLF2$ CBAEFLF2$
AEFLG1$ CBAEFLG1$
AEFLG2$ CBAEFLG2$
AEFLS1$ CBAEFLS1$
AEFLS2$ CBAEFLS2$
AEDIT$SFDT AESFDT$ CBAESFDT$
BSP$ APTIA$ CBAPTIA$
APTID$ CBAPTID$
APTIS$ CBAPTIS$
APTIU$ CBAPTIU$
APTNL$ CBAPTNL$
CPTIA$ CBCPTIA$
CPTID$ CBCPTID$
CPTIS$ CBCPTIS$
CPTIU$ CBCPTIU$
CPTNL$ CBCPTNL$
EPTIA$ CBEPTIA$
EPTID$ CBEPTID$
EPTIS$ CBEPTIS$
EPTIU$ CBEPTIU$
EPTNL$ CBEPTNL$
ETIA$ CBETIA$
ETID$ CBETID$
ETIS$ CBETIS$
ETIU$ CBETIU$
ETNL$ CBETNL$
FPTIA$ CBFPTIA$
FPTID$ CBFPTID$
FPTIS$ CBFPTIS$
FPTIU$ CBFPTIU$
E–2 7833 1733–004

Table E–1. SYSLIB$1 Entry Points
SYSLIB Common Bank Entry Points
Element Name Relocatable Entry Point Common Bank Entry Point
BSP$ (cont.) FPTNL$ CBFPTNL$
PTATWT$ CBPTATWT$
PTCTWT$ CBPTCTWT$
PTETWT$ CBPTETWT$
PTEWT$ CBPTEWT$
PTFTWT$ CBPTFTWT$
RFTI$ CBRFTI$
RFTI$$ CBRFTI$$
RPFAPT$ CBRPFAPT$
RPFCPT$ CBRPFCPT$
RPFEPT$ CBRPFEPT$
RPFET$ CBRPFET$
RPFFPT$ CBRPFFPT$
WFTI$ CBWFTI$
WPFAPT$ CBWPFAPT$
WPFCPT$ CBWPFCPT$
WPFEPT$ CBWPFEPT$
WPFET$ CBWPFET$
WPFFPT$ CBWPFFPT$
CABSAD$ CABSAD$ CBCABSAD$
CAINIT$ CBCAINIT$
CBX$ CBCBX$
CSX$ CBCSX$
CSYMVL$ CBCSYMVL$
CONWRD$ CWCLEAR$ CBCWCLEAR$
CWSET$ CBCWSET$
CRELAD$ CBN$ CBCBN$
CRELAD$ CBCRELAD$
CRINIT$ CBCRINIT$
CSN$ CBCSN$
EDESC$ CBEDESC$
7833 1733–004 E–3

SYSLIB Common Bank Entry Points
Table E–1. SYSLIB$1 Entry Points
Element Name Relocatable Entry Point Common Bank Entry Point
CRELAD$ (cont.) FHT$ CBFHT$
GETPSF$ GETPSFN$ CBGETPSFN$
GETPSF$ CBGETPSF$
ID$ ID$ CBID$
INFOR$ DUSE$ CBDUSE$
RINF$ CBRINF$
SELT$ CBSELT$
SINF$ CBSINF$
SFDT$ SFDT$ CBSFDT$
STARTSFDT$ CBSTARTSFDT$
Table E–2 lists the routines and entry points for SYSLIB common bank SYSLIB$2.
Table E–2. SYSLIB$2 Entry Points
Element Name Relocatable Entry Point Common Bank Entry Point
MFDSP$ MFDSP$ CBMFDSP$
E–4 7833 1733–004

SYSLIB Common Bank Entry Points
Table E–3 lists the routines and entry points for SYSLIB common bank SYSLIB$3.
Table E–3. SYSLIB$3 Entry Points
Element Name Relocatable Entry
Point
FDASC$ ASCFD$ CBASCFD$
FDASC$ CBFDASC$
Common Bank Entry Point
SAR$ATREAD$G SAR$ATR$PG CBSAR$ATR$PG
SAR$INATR$PG CBSAR$INATR$
SAR$RSATR$PG CBSAR$RSATR$
SAR$COM$G SAR$COM$PG CBSAR$COM$PG
SAR$READ$G SAR$CLOSI$PG CBSAR$CLOSI$
SAR$OPENI$PG CBSAR$OPENI$
SAR$READ$PG CBSAR$READ$P
SDFI SDFIC$ CBSDFIC$
SDFINT$ CBSDFINT$
SDFIOA$ CBSDFIOA$
SDFIO$ CBSDFIO$
SDFI$ CBSDFI$
Table E–4 lists the routines and entry points for SYSLIB common bank SYSLIB$4.
Table E–4. SYSLIB$4 Entry Points
Element Name Relocatable Entry Point Common Bank Entry Point
SAR$WRITE$G SAR$CLOSO$PG CBSAR$CLOSO$
SAR$OPENO$PG CBSAR$OPENO$
SAR$WCNTL$PG CBSAR$WCNTL$
SAR$WRITE$PG CBSAR$WRITE$
SDFO SDFOC$ CBSDFOC$
SDFOOSF$ CBSDFOOSF$
SDFOO$ CBSDFOO$
SDFO$ CBSDFO$
7833 1733–004 E–5

SYSLIB Common Bank Entry Points
E–6 7833 1733–004

Appendix F
Interface to Selected Extended Mode
Executive Requests
This appendix describes an interface from Extended Mode Object Modules (EMOM) to a
small subset of basic mode Executive requests (ER). The interface allows a MASM
program executing in Extended Mode (as an object module) to perform selected ERs.
The purpose of this interface is to provide the EMOM programmer with a way to dump
data and perform simple symbiont requests. This is a temporary solution only, provided
for the EMOM programmer’s convenience until the Exec callable interfaces are available.
To use this interface, the MASM program uses PROCs to execute ERs. These PROCs
save the contents of all registers they use (including B-registers), jump to a basic mode
SYSLIB common bank (SYSLIB$1), execute the ER, return to the EMOM, and restore
the contents of registers they use. These PROCs are contained in the omnibus element
EM2CB$P, which must be obtained by the MASM ‘$INCLUDE’ directive. The element
EM2CB$P is contained in the SYSLIB product file. No file name is necessary on the
$INCLUDE directive if SYSLIB is installed using the default product file name
SYS$LIB$*SYSLIB.
This interface requires MASM level 4R2 (or later) and Exec level 40R1 (or later).
F.1. Calling Sequence
The EM to ER interface PROCs in element EM2CB$P call the EM$ERS routine in the
SYSLIB common bank. The following ERs may be performed by calling these PROCs:
APRINT$ PRINT$ SNAP$
AREAD$ READ$ TREAD$
ATREAD$
7833 1733–004 F–1

Interface to Selected Extended Mode Executive Requests
Calling Sequence
EM$xxxxx pkt,b-reg
Parameters
xxxxx
pkt
b-reg
The ER mnemonic to be performed; READ, AREAD, PRINT, APRINT, TREAD,
ATREAD, or SNAP.
The label (18-bit offset from zero) of the packet generated by the appropriate
EM$xxxxPKT PROC.
The B-register of the bank containing the packet generated by the appropriate
EM$xxxxPKT PROC.
Each EM$xxxxx PROC call switches to a basic mode bank, performs the ER, and
switches back to the extended mode bank.
F.2. Packet Generation
The PROCs in the following subsections generate the required packets for the Extended
Mode interfaces to ERs.
F.2.1. EM$READPKT
The EM$READPKT PROC generates the packet for the EM$READ and EM$AREAD
PROCs.
Calling Sequence
label EM$READPKT buffer
or
label EM$AREADPKT buffer
Parameters
buffer
The address (18-bit offset from zero) of the buffer into which the image will be read.
The buffer parameter may be set at execution time, and is located at word 2 of the
packet (packet address + 1).
F–2 7833 1733–004

Interface to Selected Extended Mode Executive Requests
The buffer must be either in the same bank that contains the packet or in a bank that is
based on B15 when EM$READ or EM$AREAD is called.
The status word from the ER READ$/AREAD$ is returned in word 3 of the packet
(packet address + 2). S2 of word 3 contains an EOF flag; a nonzero value indicates an
end-of-file condition. S1 of word 3 contains the bit settings returned from the ER
READ$/AREAD$ request (bits 35 to 30). H2 of word 3 contains the number of words
read by EM$READ/EM$AREAD into the buffer. The buffer is not space filled if the
length of the image read is shorter than the length of the buffer.
F.2.2. EM$PRINTPKT
The EM$PRINTPKT PROC generates the packet for the EM$PRINT and EM$APRINT
PROCs.
Calling Sequence
label EM$PRINTPKT buf,len[,linespa]
or
label EM$APRINTPKT buf,len[,linespa]
Parameters
buf
len
linespa
The address (18-bit offset from zero) of the buffer containing the image to be
printed.
The word length of the image to be printed.
The line spacing for the image to be printed (if omitted, the default is one).
The buf, len, and linespa parameters may also be set at execution time. The buf
parameter is located at word 3 of the packet (packet address + 2). The len parameter is
located at S3 of word 2 of the packet, and the linespa parameter is located at T1 of word
2.
The buffer must be in either the same bank that contains the packet or in a bank that is
based on B15 when EM$PRINT or EM$APRINT is called.
7833 1733–004 F–3

Interface to Selected Extended Mode Executive Requests
F.2.3. EM$TREADPKT
The EM$TREADPKT PROC generates the packet for the EM$TREAD and EM$ATREAD
PROCs.
Calling Sequence
label EM$TREADPKT outbuf,len,linespa,inbuf
or
label EM$ATREADPKT outbuf,len,linespa,inbuf
Parameters
outbuf
len
linespa
inbuf
The address (18-bit offset from zero) of the buffer containing the image to be
printed.
The word length of the image to be printed.
The line spacing for the image to be printed (if omitted, the default is one).
The address (18-bit offset from zero) of the buffer to read the input image into.
The outbuf, len, linespa, and inbuf parameters may also be set at execution time.
The outbuf parameter is located at word 3 of the packet (packet address + 2). The len
parameter is located at S3 of word 2 of the packet, and the linespa parameter is located
at T1 of word 2. The inbuf parameter is located at word 4 of the packet.
The buffers must be in either the same bank that contains the packet or in a bank that is
based on B15 when EM$TREAD or EM$ATREAD are called.
The status word from ER TREAD$/ATREAD$ is returned in word 5 (packet address + 4)
of the packet. S2 of word 5 contains an EOF flag; a non-zero value indicates an end-offile
condition. S1 of word 5 contains the bit settings returned from the ER
READ$/AREAD$ request (bits 35 to 30). H2 of word 5 contains the number of words
read by EM$READ/EM$AREAD into the input buffer. The input buffer is not space filled
if the length of the image read is shorter that the length of the input buffer.
F–4 7833 1733–004

F.2.4. EM$SNAPPKT
Interface to Selected Extended Mode Executive Requests
The EM$SNAPPKT PROC generates the packet for the EM$SNAP PROC.
Calling Sequence
label EM$SNAPPKT snap-id,xar,len,address
Parameters
snap-id
xar
len
address
The snapshot identifier, from 1 to 6 characters (in quotes).
The bits identifying which registers to dump (same as for L$SNAP PROC).
The number of words to dump.
The address (18-bit offset from zero) to start dumping words from.
All of the parameters may also be set at execution time. The snap-id parameter is
located at word 2 of the packet (packet address + 1). The xar parameter is located in bits
35 to 33 of word 3 of the packet. The len and address parameters are located in bits 32
to 18 and in H2 of word 3, respectively.
The dump address must be in either the same bank that contains the packet or in a bank
that is based on B15 when EM$SNAP is called.
The value given for address must be greater than the highest address of the SYSLIB$1
common bank rounded up to the next highest 01000. The highest address of the
SYSLIB$1 common bank is given in Table D–2. This is necessary because common bank
SYSLIB$1 is based to perform the ER SNAP$ and any address to be dumped that
overlaps the SYSLIB$1 address limits will give incorrect results.
7833 1733–004 F–5

Interface to Selected Extended Mode Executive Requests
F.3. Example
The following example uses the EM$APRINT PROC to print a line of ASCII characters
from an EMOM:
$ASCII
$EXTEND
$OBJ
$INCLUDE ‘MAXR$’
$INCLUDE ‘OM$DEF’
$INCLUDE ‘EM2CB$P’
.
OM$USE_LV LVBANK,,B2
.
$(0) $BANK OM$DATA_EMB,050000 ‘DBA . EM data bank
DSTART
APRTPKT EM$APRINTPKT APRTBUF,APRTBUFL . Packet
APRTBUF ‘Print an ASCII line.’ . ASCII image to print
APRTBUFL $EQU $-APRTBUF . Word length
.
$(1) $BANK OM$CODE_EMB,01000 ‘IBANK’ . EM code bank
START$*
LBU B2,R0 . Load Link Vector
bank
. virtual address into
B2
OM$LOAD_BDR B3,DSTART,,B2 . Base data bank on B3
.
EM$APRINT APRTPKT,B3 . Print ASCII start
line
.
RTN . Program completed
$END
In this example, the EM$APRINTPKT PROC generates the packet for the EM$APRINT
PROC. The ASCII line to be printed is at label APRTBUF. The data bank containing the
image and the packet is based on B3. The EM$APRINT PROC performs the ER
APRINT$.
F–6 7833 1733–004

Appendix G
INFOR Information
When a program is executed as a processor, the OS 2200 Exec converts the processor
call statement into internal format (INFOR) and supplies it as input data to the first
symbiont read operation performed by the program.
Note: This conversion occurs only for programs that are executed as a processor
(@program) and not for programs executed with the @XQT control statement (@XQT
program).
G.1. INFOR Identifiers for Processor Call Statement
The following diagram shows the general format of a processor call statement and the
parts that are identified by INFOR.
INFOR identifies the processor,options part of the processor call statement as field type
0. This is referred to as the command field. It is composed of field 1 and the option
field. The field?1, field?2, ...,field?n part of the call statement is identified as field type 1
and is referred to as the specification field. It is composed of a variable number of
fields. INFOR does not include the label field and comment field of the processor call
statement.
Note: In other Unisys documents, the command field may be referred to as the
processor field or operation field. The specification field may be referred to as the
operand field, parameter operand, or parameter field.
7833 1733–004 G–1

INFOR Information
A field in the processor call statement contains information that conforms to the syntax
conventions of a file name or element name, as specified in the Executive Control
Language (ECL) and FURPUR Reference Manual. The format of the standard
filename.eltname notation consists of 8 parts. The following diagram shows how these
parts are identified by INFOR.
INFOR identifies each part of the filename.eltname in a field by its assigned subfield
number. For example, the filename is always identified as subfield number 2, and
eltname is always identified as subfield number 6. The character data contained within
the subfield is referred to as the symbolic subfield.
G–2 7833 1733–004

G.2. The INFOR Table
The format of the INFOR table is as follows:
INFOR Information
7833 1733–004 G–3

INFOR Information
Word 0
Bits 0–9
Type
Control statement type number. If these 10 bits are placed right-justified and
zero-filled in a 36-bit word, the result value indicates the following:
0051 The INFOR table is for a processor call.
0100 The INFOR table is for a FURPUR statement.
Note: In an octal dump of word 0, the 4 leftmost octal digits would be 0244 if the
INFOR table is for a processor call and the A and B options were not
specified.
Bits 10–35
Options
These 26 bits are master bits representing the options that were specified in the
option field of the processor call statement. Bit 10 is set if A was specified, bit
11 is set if B was specified, ..., bit 35 is set if Z was specified.
Note: The option field has no field number associated with it and has no subfield
descriptions generated for it.
Subfield Description
This is an entry of 2 or 3 words consisting of the following parts:
• Subfield control word
• Symbolic subfield
There is one subfield description for each subfield that was specified in the processor
call statement.
G–4 7833 1733–004

Subfield Control Word
The following 1-word entry provides information about the subfield.
Bits 0–5
Field Type (FT)
Bits 6–11
INFOR Information
Indicates whether the subfield is in the command field or in the specification
field. The possible values are
0 Command field
1 Specification field
Field Number (FN)
Bits 12–17
The field number (within the field type) that contains the subfield. In the
processor call statement, fields are numbered beginning with 1, left to right, and
are separated by commas. The highest field number is 63. If more than 63
fields are entered in the processor call statement, the 64th and following fields
are numbered beginning with 1.
Subfield Number (SFN)
Identifies which part of the filename.eltname notation is being described by the
subfield. The possible values are
1 File qualifier
2 File name
3 File cycle
4 Read key
5 Write key
6 Element name
7 Version name
8 Element cycle
7833 1733–004 G–5

INFOR Information
Bits 18–23
File Continuation Indicator (FCI)
Bits 24–29
The possible values are
075 The Fieldata code for the period (.) character. This value indicates that
the subfield is the first one of the field, and the field contains a leading
period.
000 Value used for all other cases.
Character Count (CC)
Bits 30–35
A value in the range 1 to 6. The character count indicates the number of
characters in the last word of the symbolic subfield.
Word Count (WC)
A value of 1 or 2. The word count indicates the number of words in the
symbolic subfield of the subfield description.
Symbolic Subfield
This is the character data that was entered for the subfield in the processor call
statement. It is a Fieldata character string that uses either 1 or 2 words as indicated by
the WC value. Each word can contain up to 6 characters. The number of characters in
the symbolic subfield can be calculated using the following formula:
6 * (WC - 1) + CC
The characters are left-justified, and the unused rightmost character positions in the last
word are space-filled.
G–6 7833 1733–004

INFOR Information
The range for number of characters and number of words in the symbolic subfield is as
follows:
SFN Subfield Name Number of Characters Number of Words
1 File qualifier 1 to 12 1 or 2
2 File name 1 to 12 1 or 2
3 File cycle 1 to 3 1
4 Read key 1 to 6 1
5 Write key 1 to 6 1
6 Element name 1 to 12 1 or 2
7 Version name 1 to 12 1 or 2
8 Element cycle 1 to 3 1
G.3. INFOR Table Conventions
The following conventions are used when generating the INFOR data:
• Except for one special situation, a subfield description is generated only if symbolic
subfield information has been entered for that subfield number in the processor call
statement. The exception is if a field in the processor call statement contains a file
name with a leading asterisk (*) character. For this situation, a subfield description is
generated as if a qualifier of 12 spaces had been entered in that field in the
processor call statement.
• If a field in the processor call statement contains a leading period, the first subfield
description generated for the field will contain a value of 075 in the FCI part of the
subfield control word.
• If the symbolic information in the processor call statement uses a character type
other than Fieldata, it is first translated into Fieldata before being put in the INFOR
table. For example, if lowercase ASCII characters are entered in the processor call
statement, the symbolic subfields in the INFOR table will contain the corresponding
uppercase characters in Fieldata.
• If a processor call statement is continued onto more than one line using the
semicolon (;), the INFOR is generated as if the call statement were on one line.
7833 1733–004 G–7

INFOR Information
G.4. INFOR Table Example
Assume that the following processor call statement is entered to execute program.abs
with c and z options and 3 fields in the specification field.
The following octal word would be generated for word 0 of INFOR:
024440000001
The following subfield descriptions would be generated in the INFOR table:
Field 1 of command field
FT FN SFN FCI CC WC Symbolic Subfield
00 01 02 00 01 02 PROGRAM∆∆∆∆∆
00 01 06 00 03 01 ABS∆∆∆
Field 1 of specification field
FT FN SFN FCI CC WC Symbolic Subfield
01 01 01 00 06 02 ∆∆∆∆∆∆∆∆∆∆∆∆
01 01 02 00 05 01 FILE1∆
01 01 05 00 06 01 WRTKEY
01 01 06 00 04 01 ELT1∆∆
01 01 010 00 01 01 1∆∆∆∆∆
Field 2 of specification field
No subfield descriptions are generated because the field contains only subfield
separators and no symbolic subfield information.
Field 3 of specification field generates 23 words of INFOR
FT FN SFN FCI CC WC Symbolic Subfield
01 03 06 075 06 02 ELEMENTNAME3
01 03 07 00 02 02 VERSION3∆∆∆∆
G–8 7833 1733–004

G.5. Reading the INFOR Table
INFOR Information
The INFOR data is supplied as input data to the first symbiont read operation performed
by the program. The program issues an ER AREAD$, ER READ$, or ER SYMB$
(READ$ function) with a buffer size of at least 27 words specified. The INFOR data is
received in blocks of 27 words or less. Only full subfield descriptions are put in the
block. If a subfield description does not fit within the last words of the block, it is put in
the next block.
Upon return from the read, register A0 contains the following information:
Bit 4 This bit is set if the data transferred into the buffer is INFOR data.
Bit 5 This bit is set if more INFOR data needs to be read.
Bits 18–35 These bits specify the number of words transferred into the buffer.
Notes:
• If the program issues a read command that specifies a buffer size less than 27
words, INFOR data may be transferred into the area beyond the end of the buffer.
• The SYSLIB and the SLIB service libraries provide INFOR routines to read the INFOR
table, to search it, and to transfer data from it to other tables. See the SLIB
Programming Reference Manual.
G.6. Determining the INFOR Table Size
If a program intends to read the entire INFOR table into memory, the size of the memory
area needed to hold the INFOR table can be determined by adding the maximum sizes
needed by the various types of information that are put in the table.
1 Word 0 of INFOR table
+ 18 Words needed for field 1 of the command field if it contains a
fully specified file name and element name.
+ 20*n
————
sum
n is the number of fields that the program expects in the
specification field. Multiply n by 20, which is the number of
words needed by each field if it contains a fully specified file
name and element name.
The sum above is the maximum size of the INFOR table.
7833 1733–004 G–9

INFOR Information
G–10 7833 1733–004

Appendix H
ASCII-like Character Sets
Table H–1 indicates which character sets are ASCII-like. ASCII-like character sets are
those that are essentially identical to the ASCII/ISO character set in the range of values
from 0000 to 0177. Where ASCII-like character sets differ from ASCII/ISO in the 0000
through 0177 range, the difference must be minor. For example, a character set that
replaces the U.S. dollar sign with a British pound sign is ASCII-like because both are
currency symbols.
Table H–1. Character Set Types
Name Octal Code Character Set Description ASCII-like
Fieldata 000 Fieldata character set
ASCII_ISO 001 ASCII/ISO character set. The data is expected
to be in the United States variant of ISO 646.
Historically, however, this value has also been
used to indicate any quarter-word character
set (in contrast to sixth-word Fieldata).
ASCII_APL 002 ASCII/APL character set Yes
EBCDIC 003 Extended Binary Coded Decimal Interchange
Code (EBCDIC)
Binary 004 Raw binary
Untyped 005 Untyped data, or application-dependent data
Column_Binary 006 Column binary format character set
OIAP 007 Reserved for use by the operating system.
Customer_Reserved 010-015 Reserved for customer use. These characters
are assumed to be ASCII-like.
Hangul 016 Hangul character set
Hanzi 017 Hanzi character set
Kanji 020 JIS-16 18-bit kanji format character set
ISO_646_US 021 United States variant of ISO 646 Yes
ISO_646_Nor_Den 022 Norway/Denmark variant of ISO 646 Yes
ISO_646_France 023 French variant of ISO 646 Yes
ISO_646_Germany 024 German variant of ISO 646 Yes
ISO_646_UK 025 United Kingdom variant of ISO 646 Yes
7833 1733–004 H–1
Yes
Yes

ASCII-like Character Sets
Table H–1. Character Set Types
Name Octal Code Character Set Description ASCII-like
ISO_646_Italy 026 Italian variant of ISO 646 Yes
ISO_646_Spain 027 Spanish variant of ISO 646 Yes
ISO_646_Sweden 030 Swedish variant of ISO 646 Yes
ISO_646_Finland 031 Finnish variant of ISO 646 Yes
ISO_646_Canada 032 Canadian variant of ISO 646 Yes
ISO_646_Netherlands 033 Netherlands variant of ISO 646 Yes
ISO_646_Portugal 034 Portuguese variant of ISO 646 Yes
ISO_Reserved 035-040 Reserved for future definition of ISO character
sets.
Customer_Reserved 041-042 Reserved for customer use. These character
sets can be defined in any way required by the
customer, but ECL commands cannot be
entered using them. They are treated as not
ASCII-like.
ISO_8859_1 043 ISO 8859.1 character set (Latin 1) Yes
ISO_8859_2 044 ISO 8859.2 character set (Latin 2) Yes
ISO_8859_3 045 ISO 8859.3 character set (Latin 3) Yes
ISO_8859_4 046 ISO 8859.4 character set (Latin 4) Yes
ISO_8859_5 047 ISO 8859.5 character set (Latin/Cyrillic) Yes
ISO_8859_6 050 ISO 8859.6 character set (Latin/Arabic) Yes
ISO_8859_7 051 ISO 8859.7 character set (Latin/Greek) Yes
ISO_8859_8 052 ISO 8859.8 character set (Latin/Hebrew) Yes
ISO_8859_9 053 ISO 8859.9 character set (Latin 5) Yes
ISO_8859_10 054 ISO 8859.10 character set (box drawing set) Yes
French_Arabic 055 French/Arabic character set Yes
Japan_ISO_3 056 Katakana character set Yes
BICS 057 BICS character set Yes
ISO_Reserved 060-062 Reserved for a future definition of ISO
character sets.
General_Reserved 063-075 Reserved for arbitrary future use. Assumed to
be not ASCII-like.
H–2 7833 1733–004
Yes
Yes

Table H–1. Character Set Types
ASCII-like Character Sets
Name Octal Code Character Set Description ASCII-like
Alternate_Location 076 Reserved for future use. This code indicates
that the user must look in an alternate location
for the actual code type.
This code is not supported; its use results in
an error.
ACD 077 Attributed character data (ACD) format
character set.
7833 1733–004 H–3

ASCII-like Character Sets
H–4 7833 1733–004

Appendix I
Extended Mode Interface to SYSLIB
I.1. General
Some SYSLIB routines can be called from Extended Mode Object Modules (EMOM)
written in MASM. This is accomplished by interfacing from extended mode banks to the
SYSLIB basic mode common banks. This appendix describes how to use the interface.
For complete information on how to use each routine, see the corresponding sections in
this manual.
The following SYSLIB routines may be called from EMOMs with this interface:
• AEDIT$ package
• BSP$
• FDASC$
• GETPSF$
• ID$
• INFOR$
• MFDSP$
Each SYSLIB routine has a MASM PROC defined to call it, and a MASM PROC defined
to generate a packet for the call. These PROCs are contained in the omnibus element
EM2CB$P, which must be obtained by the MASM ‘$INCLUDE’ directive. The element
EM2CB$P is contained in the SYSLIB product file. No file name is necessary on the
$INCLUDE directive if SYSLIB is installed using the default product file name
SYS$LIB$*SYSLIB.
This interface requires MASM level 4R2 (or higher) and Exec level 40R1 (or higher).
7833 1733–004 I–1

Extended Mode Interface to SYSLIB
I.2. Interface to the AEDIT$ Package
All of the routines in the AEDIT$ package are called with the EM$EDIT PROC. The
packet for the AEDIT$ package is generated with the EM$EDITPKT PROC.
The EM$EDIT PROC calls the ASCII editing routines in the SYSLIB common bank.
Calling Sequence:
EM$EDIT pkt,b-reg [func,param1,param2]
where:
pkt
b-reg
func
The label (18-bit offset from zero) of the packet generated by the EM$EDITPKT
PROC.
The B-register describing the bank containing the packet generated by the
EM$EDITPKT PROC.
The code for which ASCII editing function to perform. See Table I–1 for a list of all
function codes.
param1
The first additional parameter for the EM$EDIT call. This parameter varies
depending on which function code is used. See Table I–2 for a list of first parameter
values.
param2
The second additional parameter for the EM$EDIT call. This parameter varies
depending on which function code is used. See Table I–3 for a list of second
parameter values.
The func, param1, param2 parameters are optional. If they are omitted, EM$EDIT uses
the values contained in registers A1, A2, and A3, respectively. Since the EM$EDIT
PROC does not handle all combinations, either supply all parameters or all registers.
I–2 7833 1733–004

Extended Mode Interface to SYSLIB
Table I–1 contains the function codes which may be used on the EM$EDIT PROC call.
Table I–1. EM$EDIT Function Codes
Code Description
1 Initialize and enter edit mode.
2 Reenter edit mode without initializing.
3 Terminate edit mode.
4 Print image and terminate edit mode.
5 Insert a character into the image buffer.
6 Clear the image buffer.
7 Move to a column position.
8 Return the current column position.
9 Copy a string into the image buffer.
10 Edit a decimal number with leading zeroes.
11 Edit a decimal number with leading spaces.
12 Edit a decimal number with variable length.
13 Insert one word of ASCII characters into the image buffer.
14 Insert two words of ASCII characters into the image buffer.
15 Begin copying a message to the image buffer.
16 Resume copying a message to the image buffer.
17 Edit an octal number with fixed length.
18 Edit an octal number with variable length.
19 Copy a string to the image buffer but exclude any null characters.
20 Move the column pointer forward.
21 Edit a floating-point number to single-precision fixed-length decimal format.
22 Edit a floating-point number to double-precision fixed-length decimal format.
23 Edit a floating-point number to single-precision generalized format.
24 Edit a floating-point number to double-precision generalized format.
25 Edit a floating-point number to single-precision scientific format.
26 Edit a floating-point number to double-precision scientific format.
27 Place a standard format date and time string in the image buffer.
If the first parameter is an address, it must be in the same bank as the packet generated
by the EM$EDITPK PROC. All addresses are an 18-bit offset from zero.
7833 1733–004 I–3

Extended Mode Interface to SYSLIB
Table I–2 contains the possible values for the first parameter field. Function codes not
listed in the table do not require a first parameter value.
Table I–2. EM$EDIT First Parameter Field Values
Code Description
4 The line spacing for printing the image
5 The ASCII character to be inserted
7 The column number to move to
9 The address of the string to copy
10, 11, 12 The address of the integer to edit
13, 14 The address of the ASCII characters
15 The address of the string to copy
17, 18 The address of the integer to edit
19 The address of the string to copy
20 The number of columns to move forward
21–26 The address of the floating point number
Table I–3 contains the possible values for the second parameter field. Function codes
not listed in the table do not require a second parameter value.
Table I–3. EM$EDIT Second Parameter Field Values
Code Description
9 The number of characters to copy
10, 11, 17 The length of the field in characters
19 The number of characters to copy
21–26
The field length specification in the format x * /6 + y
where x is the field length in characters and y is the
number of digits following the decimal point
There are no parameters for function code 27. To edit the current date or time, set the
DATE and TIME fields in the packet generated by EM$EDITPKT to zero (default). To edit
a specified date or time, set these fields to the desired TDATE$ or TIME$ values. The
DATE field is word 17 of the packet (packet address + 16), and the TIME field is word 18
of the packet (packet address + 17).
I–4 7833 1733–004

Extended Mode Interface to SYSLIB
EM$EDIT returns the status of the call to AEDIT$ routines in the packet field CALLSTAT.
The CALLSTAT field is S3 of word 2 of the packet (packet address + 1). The possible
status are:
0 Normal return from the AEDIT$ routine
1 Error return from AEDIT$ (for function code 27 only)
2 Illegal value given for the AEDIT$ function code
EM$EDIT constructs the ASCII image in a buffer contained in the packet generated by
EM$EDITPKT. The address of the first word of the buffer is identified by the
externalized label EM$EDITBUF. The value of EM$EDITBUF is the offset from zero to
the start of the buffer.
Packet Generation
The EM$EDITPKT PROC generates the packet for the Extended Mode interface to the
AEDIT$ routines. This packet is required by the EM$EDIT PROC.
Calling Sequence:
label EM$EDITPKT buflen ['MSG', msg][ 'FPS', fps] :
['FPR', fpr] ['DPC',dpc] ['SPC', spc] :
['DFT', dft] ['TFT',tft] ['SEP', sep]
where:
buflen
The length in words of the data area used to contain the image constructed by
AEDIT$ This buffer is part of the EM$EDITPKT, and the address of the first word is
identified by the label EM$EDITBUF.
msg, fps, fpr, dpc, spc, dft, tft, sep
Optional parameters, as defined in Section 4.
I.3. Interface to BSP$
All of the functions of the BSP$ routine are called with the EM$BSP PROC. The packet
for BSP$ is generated with the EM$BSPPKT PROC.
Calling Sequence:
EM$BSP pkt, b-reg [func,param1,param2]
where:
pkt
The label (18-bit offset from zero) of the packet generated by the EM$BSPPKT
PROC.
7833 1733–004 I–5

Extended Mode Interface to SYSLIB
b-reg
func
The B-register of the bank containing the packet generated by the EM$BSPPKT
PROC.
The code for which BSP$ function to perform. See Table I–4 for a list of all function
codes.
param1, param2
Additional parameter for some function codes. See Table I–5 for a list of parameter
values. Functions 2 through 6 require one additional parameter. Functions 10 and
11 require two additional parameters.
The func, param1, and param2 parameters are optional. If func is omitted or specified as
0, EM$BSP uses the value contained in register A1.
If the function requires one parameter:
• If param1 is omitted or specified as 0, EM$BSP uses the value contained in register
A2.
• param2 should be omitted.
If the function requires two parameters:
• If param1 is omitted or specified as 0, EM$BSP uses the value contained in register
A2 modifier (bits 18–35).
• If param1 is specified, even as 0, param2 should also be specified.
• If param2 is omitted or specified as 0, EM$BSP uses the value contained in register
A2 increment (bits 0–17).
I–6 7833 1733–004

Extended Mode Interface to SYSLIB
Table I–4 contains the function codes that may be used on the EM$BSP PROC call.
Table I–4. EM$BSP Function Codes
Code Description
1 Read the file table index (RFTI$).
2 Read a program file table.
3 Search the program file table for an item.
4 Add an item to the program file table.
5 Delete an item from the program file table.
6 Locate an item by its sequence number.
7 Write out the last item referenced.
8 Write out the program file table.
9 Write the file table index back.
10 Change an item in the program file table.
11 Read the file table index (RFTI$$).
12 Mark the last item referenced as updated.
Table I–5 contains the possible values for the parameter field. Function codes not listed
in the table do not require a parameter value.
Table I–5. EM$BSP Parameter Field Values
Code Description
2 The code for which program file table to read:
1 Element table
2 Assembler procedure table
3 COBOL procedure table
4 FORTRAN/PLUS procedure table
5 Entry point table
3 The address of the search packet.
4 The address of the add packet.
5 The address of the delete packet.
6 The sequence number of the item to locate.
10 Param1 is the address of the search packet. Param2 is
the address of the change packet.
11 Param1 is the BSP$ interface level. Param2 is the
program file format for an empty file.
7833 1733–004 I–7

Extended Mode Interface to SYSLIB
If the parameter is an address, it must be in the same bank as the packet generated by
the EM$BSPPKT PROC. All addresses are an 18-bit offset from zero.
The buffer for file table index (FTI) is contained in the packet generated by the
EM$BSPPKT PROC. The first word of the FTI is identified by the externalized label
EM$FTI. The value of EM$FTI is the offset from zero to the start of the FTI.
EM$BSP returns the status of the call to BSP$ in the packet field CALLSTAT. The
CALLSTAT field is S3 of word 2 of the packet (packet address + 1). The possible status
is
0 Normal return from BSP$
1 Error return from BSP$, error code in field A0SAVE
2 Illegal value given for the BSP$ function code
3 Illegal value given for the table type (TBLTYPE field)
For CALLSTAT codes 0 and 1, the contents of registers A0, A1, and A2 from BSP$ are
returned in packet fields A0SAVE, A1SAVE, and A2SAVE, respectively. These fields are
at words 3, 4, and 5 of the packet.
Packet Generation
The EM$BSPPKT PROC generates the packet for the Extended Mode interface to BSP$.
This packet is required for the EM$BSP PROC.
Calling Sequence:
label EM$BSPPKT buflen [,filename]
where:
buflen
The word length of the buffer used to hold the program file table. The length should
be 28*(5+4n), where n is a positive integer. The minimum length is 252 words. For
maximum efficiency, the buffer length should be large enough to contain the entire
table, including the size of entries to be added.
filename
The12-Fieldata-character internal file name of the file to be accessed (in quotes).
This parameter is optional; if omitted, the caller must place the internal file name at
location EM$FTI (an externalized label from this PROC).
The packet generated by the EM$BSPPKT PROC contains the buffers for the FTI and the
program file tables. It is not necessary to allocate additional space for them.
I–8 7833 1733–004

I.4. Interface to FDASC$
Extended Mode Interface to SYSLIB
The FDASC$ routine is called with the EM$FDASC PROC. The packet for the FDASC$
routine is generated with the EM$FDASCPKT PROC.
The EM$FDASC PROC calls the FDASC$ routine in the SYSLIB common bank.
Calling Sequence:
EM$FDASC pkt,b-reg [func]
where:
pkt
b-reg
func
The label (18-bit offset from zero) of the packet gnerated by the EM$FDASCPKT
PROC.
The b-register of the bank containing the packet generated by the EM$FDASCPKT
PROC.
The code for which FDASC$ function to perform:
1 Convert a Fieldata image to ASCII
2 Convert an ASCII image to FIeldata
The func parameter is optional. If it is omitted, EM$FDASC uses the value contained in
register A1.
EM$FDASC performs character set translation on Fieldata and ASCII images. The caller
must place the image to be transferred in the input buffer, and EM$FDASC returns the
translated image in the output buffer. The input and output buffers must be specified in
the packet generated by the EM$FDASCPKT PROC.
EM$FDASC returns the status of the call to FDASC$ in the packet field CALLSTAT. The
CALLSTAT field is S3 of word 2 of the packet (packet address + 1). The possible status
is
0 Normal return from FDASC$
1 Illegal value given for the FDASC$ function code
If the normal return is taken, EM$FDASC returns the word length of the converted
image in H2 of word 3 of the packet (packet address + 2).
7833 1733–004 I–9

Extended Mode Interface to SYSLIB
Packet Generation
The EM$FDASCPKT PROC generates the packet for the Extended Mode interface to
FDASC$. This packet is required for the EM$%FDASC PROC.
Calling Sequence:
label EM$FDASCPKT len,inbuf,outbuf
where:
len
inbuf
outbuf
The word length of the input buffer.
The label (18-bit offset from zero) of the input buffer.
The label (18-bit offset from zero) of the output buffer.
The input buffer and output buffer must be in the same bank as the packet generated by
the EM$FDASCPKT PROC.
I.5. Interface to GETPSF$
The GETPSF$ routine is called with the EM$GETPSF PROC. The packet for the
GETPSF$ routine is generated with the EM$GETPSFPKT PROC.
Calling Sequence
EM$GETPSF pkt,b-reg [func,param]
where:
pkt
b-reg
The label (18-bit offset from zero) of the packet generated by the EM$GETPSFPKT
PROC.
The B-register of the bank containing the packet generated by the EM$GETPSFPKT
PROC.
I–10 7833 1733–004

func
param
The code for which GETPSF$ function to perform:
1 Assign n program scratch files
2 Assign a specific program scratch file
An additional parameter for the following function codes:
1 The number of files requested (from 1 to 10)
2 The number of the specific file requested
Extended Mode Interface to SYSLIB
The func and param parameters are optional. If they are omitted, EM$GETPSF uses the
values contained in registers A1 and A2, respectively.
EM$GETPSF returns the status of the call to GETPSF$ in the packet field CALLSTAT.
The CALLSTAT field is S3 of word 2 of the packet (packet address + 1). The possible
status is
0 Normal return from GETPSF$
1 Error return from GETPSF$, error code in field A0SAVE
2 Illegal value given for the GETPSF$ function code
For CALLSTAT codes 0 and 1, the contents of registers A0, A1, and A2 from GETPSF$
are returned in packet fields A0SAVE, A1SAVE, and A2SAVE, respectively. These fields
are at words 3, 4, and 5 of the packet.
Packet Generation
EM$GETPSFPKT generates the 18-word packet for the Extended Mode interface to
GETPSF$. This packet is required for the EM$GETPSF PROC.
Calling Sequence
label EM$GETPSFPKT
There are no parameters for the EM$GETPSFPKT PROC.
7833 1733–004 I–11

Extended Mode Interface to SYSLIB
I.6. Interface to ID$
The ID$ routine is called with the EM$ID PROC. The packet for the ID$ routine is
generated with the EM$IDPKT PROC.
EM$ID$ calls the ID$ routine in the SYSLIB common bank.
Calling Sequence:
EM$ID pkt,b-reg
where:
pkt
b-reg
The label (18-bit offset from zero) of the packet generated by the EM$IDPKT PROC.
The B-register of the bank containing the packet generated by the EM$IDPKT PROC.
This must be the beginning of the bank that contains the packet (in other words, no
subsetting).
Packet Generation:
The EM$IDPKT PROC generates the packet for the Extended Mode interface to ID$.
This packet is required by the EM$ID PROC.
Calling Sequence:
If idbuf or hdrbuf are used, they must be in the same bank as the packet.
I–12 7833 1733–004

I.7. Interface to INFOR$
Extended Mode Interface to SYSLIB
The INFOR$ routine is called with the EM$INFOR PROC. The packet for the INFOR$
routine is generated with the EM$INFORPKT PROC.
The EM$INFOR PROC calls the INFOR$ routine in the SYSLIB common bank.
Calling Sequence:
EM$INFOR pkt,b-reg [func,param]
where:
pkt
b-reg
func
param
The label (18-bit offset from zero) of the packet generated by the EM$INFORPKT
PROC.
The B-register of the bank containing the packet generated by the EM$INFORPKT
PROC.
The code for which INFOR$ function to perform. See Table I–6 for a list of possible
function codes.
An additional parameter for some function codes. See Table I–7 for a list of possible
parameter values.
The func and param parameters are optional; if they are omitted, EM$INFOR uses the
values contained in registers A1 and A2 (and A3 for function code 4), respectively.
Table I–6 contains the function codes that may be used in the EM$INFOR PROC call.
Table I–6. EM$INFOR Function Codes
Code Description
1 Read the INFOR table (RINF$).
2 Search INFOR for a specification subfield (SINF$).
3 Transfer a field to the ELT$ table (SELT$).
4 Dynamically attach a use name to a file (DUSE$).
7833 1733–004 I–13

Extended Mode Interface to SYSLIB
Table I–7 contains the possible values for the additional parameter field. Function codes
not listed in the table do not require an additional parameter value.
Table I–7. EM$INFOR Additional Parameter Field
Values
Code Description
2 The specification field in the format ftfuss, where:
ft field type
fn field number
ss subfield number
3 The subfield notation in the format ftfu, where:
ft field type
fn field number
4 The use name to attach to the file (1 to 12 Fieldata
characters in quotes)
EM$INFOR returns the status of the call to INFOR$ in the packet field CALLSTAT.
The CALLSTAT field is S3 of word 2 of the packet (packet address + 1). The possible
status is
0 Normal return from INFOR$
1 Error return from INFOR$, error code in field A1SAVE
2 Illegal value given for the INFOR$ function code
The contents of registers A0, A1, A2, and A3 from INFOR$ are returned in packet fields
A0SAVE, A1SAVE, A2SAVE, and A3SAVE, respectively. These fields are at words 3, 4,
5, and 6 of the packet.
Packet Generation:
The EM$INFORPKT PROC generates the packet for the Extended Mode interface to
INFOR$. This packet is required by the EM$INFOR PROC. EM$INFORPKT also
generates the externalized labels INFOR$, FILE$, and ELT$. The value of each label is
the offset from zero to the first word of the data entity.
Calling Sequence:
label EM$INFORPKT tbllen
where tbllen is the word length of the INFOR table; the minimum size is 28 words.
I–14 7833 1733–004

Extended Mode Interface to SYSLIB
The buffer to hold the INFOR table is contained within the packet generated by the
EM$INFORPKT PROC. The first word of the INFOR table is identified by the
externalized label EM$INFORTBL. The value of this label is offset from zero to the start
of the table.
The caller must set the INFOR$ word to zero for the INFOR$ routine to read the INFOR
table.
I.8. Interface to MFDSP$
All functions of the MFDSP$ routine are called with the EM$MFDSP PROC. The packet
for the MFDSP$ routine is generated with the EM$MFDSPPKT PROC.
Calling Sequence
EM$MFDSP pkt,b-reg [func,param]
where:
pkt
b-reg
func
param
The label (18-bit offset from zero) of the packet generated by the EM$MFDSPPKT
PROC.
The B-register of the bank containing the packet generated by the EM$MFDSPPKT
PROC.
The code for which MFDSP$ function to perform. See Table I–8 for a list of possible
function code values.
An additional parameter for the following function. See Table I–9 for a list of second
parameter values.
The func and param parameters are optional; if they are omitted, EM$MFDSP uses the
values contained in registers A1 and A2, respectively.
7833 1733–004 I–15

Extended Mode Interface to SYSLIB
Table I–8 contains the function codes that may be used on the EM$MFDSP PROC call.
Table I–8. EM$MFDSP Function Codes
Code Description
0 Initialize MFDSP$ and get the first lead item.
1 Initialize MFDSP$ and get the first main item.
2 Get the next lead item.
3 Get sector 1 of the current lead item.
4 Get the next main item.
5 Get the next sector of the current main item.
6 Get the first DAD table for the current main item.
7 Get the next DAD table.
8 Find an item by its MFD address.
9 Convert an MFD address to the DGET file address.
Table I–9 contains the possible values for the additional parameter field. Function codes
not listed in the table do not require an additional parameter value.
Table I–9. EM$MFDSP Parameter Field Values
Code Description
8 The MFD address of the item to be found
9 The MFD address to be converted
EM$MFDSP returns the status of the call to MFDSP$ in the packet field CALLSTAT.
The CALLSTAT field in S3 of word 2 of the packet (packet address + 1). The possible
status is:
0 Normal return from MFDSP$
1 Error return from MFDSP$ (error code returned in field
A2SAVE)
2 Illegal value given for the MFDSP$ function code
For all calls by EM$MFDSP, the contents of registers A0 through A5 from MFDSP$ are
returned in packet fields A0SAVE, A1SAVE, A2SAVE, A3SAVE, A4SAVE, and A5SAVE,
respectively. These fields are at words 3 through 8 of the packet.
Packet Generation:
The EM$MFDSPPKT PROC generates the packet for the Extended Mode interface to
MFDSP$. This packet is required by the EM$MFDSP PROC.
I–16 7833 1733–004

Calling Sequence:
label EM$MFDSPPKT [buflen] [filename]
where:
buflen
Extended Mode Interface to SYSLIB
The word length of the buffer used by MFDSP$. This parameter is optional.
If omitted, a value of 4,400 words is used.
filename
The 12-Fieldata-character internal file name of the file containing the MFD
(in quotes). This parameter is optional; if omitted, the caller must place the internal
file name at location EM$MFDSPBUF, an externalized label from this PROC. The
value of this label is the offset from zero to the start of the table.
7833 1733–004 I–17

Extended Mode Interface to SYSLIB
I–18 7833 1733–004

Appendix J
Obsolete Entry Points, PROCs, and
Routines
This appendix documents PROC calls, entry points, and routines that have been
replaced. Whenever an application is updated that calls these PROCs or entry points, it
should be changed to use the new replacement.
J.1. AEDIT$–Generating the AEDIT$ Packet
The following three MASM procedures that generate the AEDIT$ packet are replaced by
the MASM PROC A$EDITPKT (see 4.1.2).
• A$EPKT (for general-purpose editing)
• A$EPKTF (for floating-point editing)
• A$EPKTSFDT (for date and time editing)
The calling sequences for these MASM procedures are described below. The
parameters in italics are supplied by the calling program. The parameters in brackets are
optional and may be omitted. If they are omitted, the default value is used.
J.1.1. A$EPKT
The A$EPKT procedure generates a seven-word AEDIT$ packet. This packet is used for
general-purpose editing.
Calling Sequence
label A$EPKT image-length,image-address [‘MSG’,msg]
J.1.2. A$EPKTF
The A$EPKTF procedure generates an 11-word AEDIT$ packet. This packet is used for
floating-point number editing.
Calling Sequence
label A$EPKTF image-length,image-address [‘MSG’,msg];
[‘FPS’,fps] [‘FPR’,fpr];
[‘DPC’,dpc] [‘SPC’,spc]
7833 1733–004 J–1

Obsolete Entry Points, PROCs, and Routines
J.1.3. A$EPKTSFDT
A$EPKTSFDT procedure generates a 14-word AEDIT$ packet. This packet is used for
date and time editing.
Calling Sequence
label A$EPKTSFDT image-length,image-address [‘MSG’,msg];
[‘FPS’,fps] [‘FPR’,fpr] [‘DPC’,dpc];
[‘SPC’,spc] [‘DFT’,date-format] [‘TFT’,time-format];
[‘SEP’,separator-character]
J.1.4. Examples of Generating the AEDIT$ Packet
Example 1
$(0)
PACKET A$EPKT 20,ASCIILINE .AEDIT$ packet
ASCIILINE $RES 20 .Data area for ASCII image
In example 1, the MASM procedure A$EPKT generates a seven-word packet at the
location PACKET in location counter 0. AEDIT$ uses this packet for general-purpose
ASCII editing, but not for floating-point numbers or data and time formats. AEDIT$ will
store the generated ASCII string in the 20-word data area at location ASCIILINE. The
message halt character defaults to “&”.
Example 2
LINELEN $EQU 33 .Length of ASCII data area
$(4)
LINE $RES LINELEN .Data area for ASCII image
PACKET A$EPKTSFDT LINELEN,LINE ‘DFT’,8 ‘TFT’,3 .AEDIT$ packet
In example 2, the MASM procedure A$EPKTSFDT generates a 14-word packet for ASCII
editing with date and time formats. AEDIT$ will store the generated ASCII string in the
33-word data area at location LINE. AEDIT$ uses date format index 8 and time format
index 3. AEDIT$ uses the default values for the msg, fps, dps, spc, and
separator-character parameters.
J.2. CONWRD$–MASM PROCs and Entry Points
These entry points to the CONWRD$ routine are replaced by the C$ONWRD PROC
(see Section 7). The common bank entry points are
BCWSET$
Sets bit 8 of the condition word; if bit 8 was already set, then set bit 7.
BCWCLEAR$
Clears bit 8 of the condition word; it does not affect bit 7.
J–2 7833 1733–004

MASM PROCs to call CONWRD$
• Relocatable element
C$WSET
normal return
and
C$WCLEAR
normal return
• Common bank
B$CWSET
normal return
and
B$CWCLEAR
normal return
Obsolete Entry Points, PROCs, and Routines
J.3. EOUT$–Generalized Output Editing Routine
The functionality of EOUT$ is now provided by the AEDIT$ and EDIT$ image
composition editing packages (see Sections 4 and 8).
EOUT$ is an interpretive routine that performs editing functions for Fieldata output
produced for a printer, communications terminal, card punch, or display console.
The interpretive instructions performed by the routine are constructed similarly to
machine language instructions. The format is
f t d x m
0 4 5 11 12 17 18 19 20 35
where:
f
t
d
Function code
Print position (printer) or character position (display console). Print position
numbering starts at zero.
Decimal point location
7833 1733–004 J–3

Obsolete Entry Points, PROCs, and Routines
x
m
Specifies indirect address and use of the simulated index register
Address (main storage location of data)
EOUT$ is called by
LMJ X11,EOUT$
There are two entry points to this subroutine. The normal entry point is EOUT$.
The other, EOUTR$, is the point for reentry after the E$TERM (terminate) function (see
J.3.4).
The addressed word in the m-field may be either in a control register or in main storage.
Any word, even if the word is in a volatile register, is permissible. If register X11 is
addressed, however, the location of the interpretive word that references X11 is output.
All registers, including volatile ones, are saved and restored. The x-field specifies indirect
addressing and the use of the single simulated index register. Its permissible values
(in octal) are as follows:
00 No action
01 Use address indirectly
02 Apply simulated index register
03 Apply simulated index register, then use address indirectly
Indirect addressing is permitted to one level only, and the x-, h-, and i- fields of the
indirectly addressed word are ignored. It is possible, however, to indirectly address
control storage. All modes may be used with indirect addressing.
The various functions are described in the following paragraphs. All may be called as
procedures. Each of the procedure calls generates one word in the correct format. The
parameters of these procedures are interpreted differently, depending on the number
written. A single parameter is taken as m; two parameters as m and x; three parameters
as t, d, and m; and four parameters as t, d, m, and x. Any missing parameters are
assumed to be zero.
The caller may obtain entry to EOUT$ by the procedure E$OUT or E$OUTR, depending
on the entry point desired. No parameters are required.
J–4 7833 1733–004

J.3.1. Editing Functions
Obsolete Entry Points, PROCs, and Routines
These editing functions convert the information to be output. In all cases, except E$A
(alphanumeric words), the field specifies the print position at which the rightmost digit,
bit, or character will be printed. The number given in parentheses following the
procedure call is the octal function code.
E$D(01)–Decimal
The address word is treated as if it were a signed decimal integer and is edited
without a decimal point unless a set function (see E$PNT, J.3.3) is in effect. Leading
zeros to the left are suppressed, and a minus sign, if any, is printed immediately to
the left of the number (also see E$OVRP, J.3.3). If the value is zero, a single zero is
printed. If a set point is in effect, the decimal number is assumed to have the
started point specified by the set point. The d-field specifies the number of decimal
digits to be printed to the right of the decimal point. If a set field function (see
E$FLD, J.3.3) with D = 0 is in effect, the specified field is treated as an unsigned
decimal integer.
E$0(02)–Octal
The d low-order bits of the addressed word are edited and printed as (d+2)/3 octal
digits, unsigned. For a full octal, binary, or alphanumeric character word, d must
always be given as 36.
E$B(03)–Binary
The d low-order bits of the addressed word are edited as d binary digits, unsigned.
E$C(04)–Alphanumeric Characters
The d low-order bits of the addressed word are edited and printed as (d+5)/6
alphanumeric characters in Fieldata code.
E$A(05)–Alphanumeric Words
The d words beginning with the addressed word are edited as 6*d characters in
Fieldata code. For this editing function only, the t-field specifies the print position at
which the leftmost character is printed.
E$E(06)–Floating-Point (FORTRAN E)
The addressed word is edited as a floating-point number with d significant digits.
Normally these are all printed to the right of the decimal point (see E$SCL, J.3.3).
A decimal exponent consisting of a sign and 2 digits is inserted immediately to the
right of the significant portion. If the floating-point number is negative, a minus sign
is inserted immediately to the left of the number (see E$OVRP, J.3.3). If the
addressed word is minus zero, there is no effect and the field is left blank.
7833 1733–004 J–5

Obsolete Entry Points, PROCs, and Routines
E$F(07)–Floating-to-Fixed (FORTRAN F)
The addressed word is assumed to be a floating-point number and is edited to fixed
point with d places following the decimal point. Negative numbers, including minus
zero, are treated as in E$E.
E$DE(26)–Double-Precision Floating-Point
This editing function is the same as E$E, with the addressed word and the
addressed word plus one edited as a double-precision, floating-point number. A
decimal exponent consisting of a sign and 3 digits is inserted immediately to the
right of the significant portion.
E$DF(27)–Double-Precision Floating-to-Fixed
EIMG$
This editing function is the same as E$F, with the addressed word and the
addressed word plus one edited as a double-precision, floating-point number.
The edited output of EOUT$ is stored in a 22-word buffer in the EOUT$ D-bank
following the externally defined label EIMG$.
E$CENT
The text at m is edited as a centered string. The parameters m and x may be given;
in addition, a third parameter is required to specify the number of characters in the
string. The string will be centered in a 128-character line and edited by a call to E$A.
J.3.2. Output Functions
The output functions serve to transmit the edited line to an output device. The device to
be used is determined by the d-field:
Printer d=0
Card Punch d=1
Display Console d=2
The word or character count is given in the t-field. This count must be given. (It is not
assumed maximum if it is given as zero.) For the printer, the word count is normally 22;
for the card punch, normally 14. For the display console, the t-field is a character count
and cannot be more than 60.
For the printer, the m-field serves to specify the number of lines to be spaced. A value
greater than the length of a logical page results in printing on the first line of the next
page. For the punch and display console, the m-field is ignored. The number given in
parentheses following the procedure call is the octal function code.
J–6 7833 1733–004

E$WT(10)–Write and Terminate
Obsolete Entry Points, PROCs, and Routines
The edited image is transmitted to the specified device, and the routine returns
control to the next instruction in machine language mode. The image is not reset to
blanks.
E$W(11)–Write
The edited image is transmitted to the specified device and the routine continues in
the interpretive mode. The image is reset to blanks.
E$WS(12)–Write and Save
The edited image is transmitted to the specified device and the routine continues to
the next instruction in the interpretive mode. The image remains available for use by
further output functions or further editing.
J.3.3. Modal Functions
The modal functions serve to enter information that affects the interpretation of one or
more of the instructions that follow. The number given in parentheses following the
procedure call is the octal function code.
E$SCL(13)–Set Scale
The contents of the address field are treated as a signed power of 10 to be applied
to any floating-point or floating-to-fixed function that follows the set scale function.
For floating-point, the scale is the number of digits to be printed to the left of the
decimal point. The exponent field is reduced accordingly, so that the resulting value
is the same as if no set scale function were in effect. Negative values of the
address (the 16-bit ones complement) introduce leading zeros after the decimal point
and increase the exponent field accordingly.
For floating-to-fixed conversion, the actual value of the resulting number is altered by
multiplying it by the power of 10 indicated by the address. The set scale function
remains in effect until it is countermanded by a new set scale. Upon initial entry to
EOUT$, the scale is assumed to be 0.
E$PNT(14)–Set Point
The set point function specifies the position of the binary point for the next editing
function to be encountered (presumably a decimal editing function). It remains in
effect only for the single edit. The address of the set point gives the number of bits
following the binary point. Negative values are permitted (see E$FLD).
7833 1733–004 J–7

Obsolete Entry Points, PROCs, and Routines
E$FLD(15)–Set Field
The set field function is used to specify a subfield of the next word to occur
(presumably decimal, octal, binary or alphanumeric character function). The t-field
specifies the left margin and the m-field the right margin. The bits of the machine
word are numbered, for the purposes of this function, from left (00) to right (35).
The d-field specifies extension of sign; if it is nonzero, the field is treated as sign.
A set field function with d=0 and t=0 may be used to treat fields, including the sign
bit, as unsigned unless m=35. (That is, a whole word must always be signed in the
event a sign is applied.)
The set field function remains in effect only for the next function encountered.
If both a set field and a set point function are in effect when editing occurs, the set
field function is applied first. In this case, the set point function specifies the binary
point counting from the right-hand end of the specified field.
E$INDX(16)–Set Index
The set index function is used to address a quantity in main storage that is to be
loaded into the single simulated index register. For any function that addresses
storage (including this one), the presence of a 1 bit in the increment (h) portion of the
address causes the simulated index to be added to the specified address before
access is made. The left half of the index register word is ignored. If the d-field is
nonzero, the contents of the m-field (with sign extension) are loaded into the
simulated index register. The set index function remains in effect until it is
countermanded by another set index function.
E$OVRP(17)–Overpunch
The overpunch function specifies that any minus signs produced by the editing
functions are to be removed from their positions in front of the edited numbers and
placed as 11-punches over the low-order digits. In the case of floating-point editing,
the sign of the mantissa is placed over the low-order digit of the mantissa and the
sign of the exponent over its low-order digit. The space that would normally contain
the sign of the exponent is omitted.
The overpunch function is initiated by its occurrence with address 1. It is
countermanded by its occurrence with address 0. Upon initial entry to EOUT$,
the overpunch mode is assumed to be off.
J.3.4. Control Functions
The control functions introduce some of the control operations available in machine
language into the interpretive language. The number in parentheses following the
procedure call is the octal function code.
J–8 7833 1733–004

E$TERM(20)–Terminate
Obsolete Entry Points, PROCs, and Routines
The terminate function returns the routine to the next instruction in machine
language. Upon reentry at point EOUTR$, all counters, modes in effect, interpretive
subroutines, and any partial image are left undisturbed. Control is returned to the
next instruction in machine code. If reentry is made at EOUT$, these are all cleared
and control is returned to the interpretive mode. Entry at EOUT$ is made by:
LMJ X11,EOUTR$
E$LINK(21)–Link
The link function forms subroutines in the editing language. Its effective address
specifies the location of the entry to a subroutine. Subroutines may be nested to a
depth of 10.
E$JUMP(22)–Jump
The jump function with a nonzero effective address causes an interpretive transfer of
control to the designated location. If the address is zero, the jump function serves
as a subroutine exit. Transfer is to the interpretive function following that link control
most recently executed for which no exit has been performed.
E$RPT(23)–Repeat
The repeat function causes the next single interpretive function to be repeated the
number of times specified in the d-field of the repeat word. A repeat function
preceding E$LINK is meaningless; for multiple execution of E$LINK, the routine
EOUT$ should be called within a machine language loop. The t- and m-fields contain
increments to the t- and m-fields of the instruction to be repeated for each
execution. Any modes set by the modal functions which would be in effect for the
first execution of a repeated instruction remain in effect for all executions.
E$CLR(24)–Clear
The clear function sets the image to blanks.
J.3.5. EOUT$–Calling Sequences
This section shows some typing EOUT$ calling sequences. (The FORTRAN formatting
merely indicates the format desired. The I/O functions in FORTRAN use an editing
scheme peculiar to themselves.)
7833 1733–004 J–9

Obsolete Entry Points, PROCs, and Routines
Example 1
The FORTRAN instruction
PRINT 100,A,I,N,B,C
100 FORMAT (6X,E20.7, I20, O20, 1P2F20.6)
is equivalent to the following interpretive sequences:
E$OUT
E$E 26,7,A
E$D 46,0,I
E$0 66,36,N
E$SCL 1
E$F 86,6,B
E$F 106,6,C
E$WT 22,0,1
Next machine language instruction.
Example 2
If this line is punched on a card punch whose output code is 1, then the last interpretive
instruction is replaced by
E$WS 14,1,0
E$WT 22,0,1
Only the first 80 columns of the image are punched.
Example 3
The FORTRAN statements
PRINT 100 (J (I), K (I), L (I), M (I), I=1,4)
100 FORMAT (20I6)
are equivalent to the following interpretive sequences:
E$RPT 30,4,1
E$D 6,0,J,2
E$RPT 30,4,1
E$D 12,0,K,2
E$RPT 30,4,1
E$D 18,0,L,2
E$RPT 30,4,1
E$D 24,0,M,2
E$WT 22,0,1
J–10 7833 1733–004

J.4. I$D–Calling Sequence
Obsolete Entry Points, PROCs, and Routines
The I$D PROC to call the ID$ routine is replaced by the I$D$ PROC (see 11.1.2).
The following MASM procedure calls ID$:
I$D pktaddr date
error return
normal return
where:
pktaddr
date
address of the ID$ packet.
address of caller-specified date and time (must be in TDATE$ format). This
parameter is optional.
The calling program can use indexing, incrementation, indirect addressing, and register
basing in specifying the addresses for pktaddr and date with the $EQUF directive in the
following format:
label $EQUF,j *u,*x,,*b
If date is included on the calling statement, the TDATE$ value at that address is used for
the execution date/time. If the date is excluded, the TDATE$ value in word 8 of the ID$
packet is used. If no value is present in word 8, the current date/time is obtained from
ER TDATE$.
Error Return
If ID$ takes the error return, either A1 or A2 contains a negative error code. If the error
occurred in ID$, A1 contains the error code; if the error occurred in SFDT$, A2 contains
the error code.
• ID$ error codes (returned in A1):
-01 An outdated version of the ID$ packet is being used.
• SFDT$ error codes (returned in A2):
-01 through -05 SFDT$ routine error; see Section 22.
The error code is also stored in the packet, in ERRCODE.
7833 1733–004 J–11

Obsolete Entry Points, PROCs, and Routines
Normal Return
The output ID$ generates may be one or more lines; this depends on the length of the
processor/program description and specified options. For each line of ID$ output, a print
control word is constructed (line-spacing, image-length, image-address) and stored
sequentially in the ID$ packet starting with word 10. The number of print control words
constructed is stored in S6 or word 0 of the ID$ packet.
If the normal return occurs, the first print control word is returned in A0.
The following procedure simplifies printing of the ID$ output:
I$DPRINT pktaddr
where pktaddr is the address of the ID$ packet.
This procedure performs an APRINT$ for each print control word. It may be called from
the I$D PROC by setting option bit 4.
All output from ID$ is directed to the current print file.
Example of Calling ID$
The following example calls the ID$ routine to generate an ASCII identification line:
$ASCII
$INCLUDE ‘MAXR$’
$(0)
IDPAC I$DPKT ‘IDLINE$ ‘Math Quiz Program (Level 8)’026
$(1)
START I$D IDPAC . Generate and print the ID line
J ERROR . Jump ahead if error return
.
. (Program code)
.
J DONE . Program complete
ERROR L$SNAP ‘ID$’,2 . Dump the A-registers
DONE ER EXIT$
$END START
This MASM routine uses the ID$ routine to create and print the following identification
line:
Math Quiz Program (Level 8) 840425 1147:31
In this example, ID$ generates the ASCII identification line in the 11-word data area at
location IDLINE. The I$DPKT procedure generates the ID$ packet (see Example 2 in the
previous subsection).
J–12 7833 1733–004

Obsolete Entry Points, PROCs, and Routines
The I$D procedure calls ID$, which generates the identification line and prints it by
executing an ER APRINT$ (because option bit 4 is set).
If ID$ takes the error return, L$SNAP prints the A registers. Otherwise, the program
continues executing.
J.5. IDLINE$ and IDONLY$–Identification Line
Routines
The IDLINE$ and IDONLY$ routines are replaced by the ID$ routine (see Section 11).
IDLINE$ and IDONLY$ are routines that provide a standard identification line for Series
1100 system, language, and utility processors. IDLINE$ and IDONLY$ are reentrant and
not quarter/third-word sensitive. Do not call IDLINE$ and IDONLY$ from a minor register
set activity.
Identification Line Format
A standard processor identification line is generated in a processor-supplied buffer called
IDBUFF. All fields but the processor name and level field are generated. The element
cycle information field is optional. All information is generated in Fieldata code beginning
after the last nonblank character and preceded by one blank character.
The format of the complete ID line is
ppplll SYSLIB mm/dd/yy hh:mm:ss (old->new)
where:
ppplll
SYSLIB
processor name and level, 12 characters or less, supplied by the processor.
SYSLIB level the processor is collected with. The form varies with the level number.
For example, SL74R1, 74R1Q1.
mm/dd/yy
month/day/year at processor call.
hh:mm:ss
hour:minute:second at processor call.
(old->new)
input-> output symbolic element cycle number (optional).
7833 1733–004 J–13

Obsolete Entry Points, PROCs, and Routines
IDBUFF
The processor must supply a buffer with an externally defined label, IDBUFF. Before
calling IDLINE$ or IDONLY$, this buffer must be initialized with the name/level field (up
to 12 characters) left-justified and the remainder of the buffer blank-filled. This buffer
must be at least six words long and up to eight, depending on the name/level length and
whether or not cycle information is requested.
The minimum IDBUFF length required is shown in Table J–1.
Table J–1. IDLINE$, IDONLY$: IDBUFF
Length
Routine Called Name and Level Length
1 Word 2 Words
IDLINE$,IDTIME$ 7 8
IDONLY$,IDTOME$ 6 7
A processor name and level greater than 12 characters may be used by defining the start
of IDBUFF as the word following the name and level. It may also be used if no more
than the last 12 characters are included within IDBUFF.
J.5.1. IDLINE$
There are two entry points to the IDLINE$ routine: IDLINE$ and IDTIME$.
J.5.1.1. IDLINE$
IDLINE$ generates the complete ID line, including symbolic element cycle information.
The element cycle information is taken from PARTBL, which is filled in by either the
SYSLIB routine PREPRM or PREPRO. The call on PREPRM or PREPRO must precede
the call on IDLINE$ or IDTIME$.
Calling Sequence
LMJ X11,PREPRO$ . or PREPRM$
J ERROR . error return from PREPRO$ or PREPRM$
LMJ X11,IDLINE$
.
PF FORM 12,6,18
LA A0,(PF 1,8,IDBUFF)
ER PRINT$
J–14 7833 1733–004

J.5.1.2. IDTIME$
Obsolete Entry Points, PROCs, and Routines
The IDLINE$ call is the equivalent of IDLINE$, except that you furnish the date (in
register R2) and time (in register R3) in ER DATE$ format. IDTIME$ can be used by a
processor that executes for a considerable time before it prints the ID line. In this case,
the actual date and time that the processor began execution are saved and then passed
to IDLINE$ in registers R2 and R3.
J.5.2. IDONLY$
There are two entry points to the IDONLY$ routine: IDONLY$ and IDTOME$.
J.5.2.1. IDONLY$
IDONLY$ generates the ID line without the symbolic element cycle information.
IDONLY$ can be used by processors that do not create or update elements. An
externally defined PARTBL is not required.
Calling Sequence
LMJ X11,IDONLY$
.
PF FORM 12,6,18
LA A0,(PF 1,7,IDBUFF)
ER PRINT$
J.5.2.2. IDTOME$
The IDTOME$ call is the equivalent of IDONLY$, except that you furnish the date (in R2)
and time (in R3) in ER DATE$ format.
J.6. SFDT$–MASM Calling Sequence
The S$FDT PROC to call the SFDT$ routine is replaced by the S$FDT$ PROC (see
22.1.2).
The S$FDT procedure call obtains the standard format for date, time, or both date and
time:
S$FDT pkt-addr date time
error return
normal return
where:
pkt-addr
the address of the five-word SFDT$ packet.
7833 1733–004 J–15

Obsolete Entry Points, PROCs, and Routines
date
time
the address of a caller-specified date and time (must be in TDATE$ format). This
parameter is optional.
the address of a caller-specified time (must be in TIME$ format). This parameter is
optional.
J.7. SYS$RLIB$ID–RLIB Identification
SYS$RLIB$ID is an element that contains the level identification of the system
relocatable library file, SYS$*RLIB$ (also referred to as RLIB). It defines the following
external labels:
RLIB$ID1 First four characters of ID in ASCII
RLIB$ID2 Second four characters of ID in ASCII
RLIB$ID3 Third four characters of ID in ASCII
If a site makes changes to SYS$*RLIB$, it should update the level identification of this
file.
The SYS$*RLIB$ file ID is updated by assembling the element SYS$RLIB$ID and
supplying the new ID in the fourth parameter field of the @MASM processor call. The ID
may be from 1 to 12 characters long.
Example
@MASM,S SYS$*RLIB$.SYS$RLIB$ID,.SYS$RLIB$ID,,840713
where 840713 is the new ID.
This example generates the following definitions:
RLIB$ID1* $EQU ‘8407’
RLIB$ID2* $EQU ‘13∆∆’
RLIB$ID3* $EQU ‘∆∆∆∆’
J–16 7833 1733–004

Obsolete Entry Points, PROCs, and Routines
J.8. PIRCB$ Common Bank Entry Points
Table J–2 lists the routines and entry points for SYSLIB common bank PIRCB$. PIRCB$
is replaced by the common banks SYSLIB$1, SYSLIB$2, SYSLIB$3, and SYSLIB$4. The
common bank entry points listed in Table J–2 should not be used; instead, use the
common bank calling sequence documented in the description of these routines.
Table J–2. PIRCB$ Entry Points
Element Name Relocatable Entry Point Common Bank Entry Point
BSP$ APTIA$ BAPTIA$
APTID$ BAPTID$
APTIS$ BAPTIS$
APTNL$ BAPTNL$
CPTIA$ BCPTIA$
CPTID$ BCPTID$
CPTIS$ BCPTIS$
CPTNL$ BCPTNL$
EPTIA$ BEPTIA$
EPTID$ BEPTID$
EPTIS$ BEPTIS$
EPTNL$ BEPTNL$
ETIA$ BETIA$
ETID$ BETID$
ETIS$ BETIS$
ETNL$ BETNL$
FPTIA$ BFPTIA$
FPTID$ BFPTID$
FPTIS$ BFPTIS$
FPTNL$ BFPTNL$
PTATWT$ BPTATWT$
PTCTWT$ BPTCTWT$
PTETWT$ BPTETWT$
PTEWT$ BPTEWT$
PTFTWT$ BPTFTWT$
RFTI$ BRFTI$
RPFAPT$ BRPFAPT$
7833 1733–004 J–17

Obsolete Entry Points, PROCs, and Routines
Table J–2. PIRCB$ Entry Points
Element Name Relocatable Entry Point Common Bank Entry Point
BSP$ (cont.) RPFCPT$ BRPFCPT$
RPFEPT$ BRPFEPT$
RPFET$ BRPFET$
RPFFPT$ BRPFFPT$
WFTI$ BWFTI$
WPFAPT$ BWPFAPT$
WPFCPT$ BWPFCPT$
WPFEPT$ BWPFEPT$
WPFET$ BWPFET$
WPFFPT$ BWPFFPT$
CONWRD$ CWCLEAR$ BCWCLEAR$
CWSET$ BCWSET$
FDASC$ ASCFD$ BASCFD$
FDASC$ BFDASC$
ID$ ID$ BID$
SAR$ATREAD$G SAR$ATR$PG BSAR$ATR$P
SAR$INATR$PG BSAR$INATR$P
SAR$COM$G SAR$COM$PG BSAR$COM$P
SAR$READ$G SAR$CLOSI$PG BSAR$CLOSI$P
SAR$OPENI$PG BSAR$OPENI$P
SAR$READ$PG BSAR$READ$P
SAR$WRITE$G SAR$CLOSO$PG BSAR$CLOSO$P
SAR$OPENO$PG BSAR$OPENO$P
SAR$WCNTL$PG BSAR$WCNTL$P
SAR$WRITE$PG BSAR$WRITE$P
SDFI SDFIC$ BSDFIC$
SDFINT$ BSDFINT$
SDFIOA$ BSDFIOA$
SDFIO$ BSDFIO$
SDFI$ BSDFI$
J–18 7833 1733–004

Obsolete Entry Points, PROCs, and Routines
Table J–2. PIRCB$ Entry Points
Element Name Relocatable Entry Point Common Bank Entry Point
SDFO SDFOC$ BSDFOC$
SDFOOSF$ BSDFOOSF$
SDFOO$ BSDFOO$
SDFO$ BSDFO$
SFDT$ SFDT$ BSFDT$
STARTSFDT$ BSTARTSFDT$
7833 1733–004 J–19

Obsolete Entry Points, PROCs, and Routines
J–20 7833 1733–004

Appendix K
Related Product Information
OS 2200 Exec System Software Administration Reference Manual (7831 0323).
Unisys Corporation.
OS 2200 Exec System Software Executive Requests Programming Reference Manual
(7830 7899). Unisys Corporation.
OS 2200 Executive Control Language (ECL) and FURPUR Reference Manual
(7830 7949). Unisys Corporation.
OS 1100 Meta-Assembler (MASM) Programming Reference Manual (7830 8269).
Unisys Corporation.
OS 2200 Exec System Software Installation and Configuration Guide (78306 7915).
Unisys Corporation.
OS 1100 Collector Programming Reference Manual (7830 9887). Unisys Corporation.
OS 1100 LIST Processor (LIST) End Use Guide (7831 3384). Unisys Corporation.
OS 1100 Universal Compiling System (UCS) FORTRAN Programming Reference
Manual Volume 1, FORTRAN Statements (7831 0489). Unisys Corporation.
Unisys e-@ction Application Development Solutions FORTRAN Compiler Programming
Reference Manual Volume 2: Compiler and System Interface (7830 7477).
Unisys Corporation.
OS 1100 Universal Compiling System (UCS) PLUS Programming Reference Manual
Volume 1, PLUS Statements (7831 0497). Unisys Corporation.
OS 1100 Universal Compiling System (UCS) PLUS Programming Reference Manual
Volume 2, Compiler and System Interface (7831 2287). Unisys Corporation.
OS 2200 Data Structures Programming Reference Manual (7833 3481).
Unisys Corporation.
OS 2200 Service Library Programming Reference Manual (7830 7857).
Unisys Corporation.
OS 2200 System Services Programming Reference Manual (7833 4455).
Unisys Corporation.
7833 1733–004 K–1

Related Product Information
OS 1100 Exec System Software Executive Request Programming Quick-Reference Guide
(7830 9952). Unisys Corporation.
OS 1100 Postmortem Dump (PMD) Programming Reference Manual (UP-8725).
Unisys Corporation.
K–2 7833 1733–004

Glossary
B
bank descriptor index (BDI)
An index into the bank descriptor table (a data structure defined by the Exec). Practically,
BDIs are the equivalent of symbolic bank names. Program BDIs are assigned by the
Collector, whereas configured common bank BDIs are managed by the Exec, COMUS,
and the systems analyst, or
C
An integer value used as a relative index into a bank descriptor table (BDT). The BDI
points to a bank descriptor (BD) in the BDT that defines storage allocation for a program
segment, or
An unsigned integer in the range of zero to n-1, where n is the maximum number of
bank descriptors allowed in a given bank descriptor table. The integer is used to locate a
bank descriptor in the bank descriptor table. The first bank descriptor has an index of
zero and the nth bank descriptor has an index of n-1. The bank descriptor index is the
low order 16 bits of L,BDI and the low order 12 bits of E,LS,BDI.
Collector
A system processor (called using @MAP) that joins relocatable elements into an absolute
element.
D
DAD
E
ECL
Abbreviation for device area descriptor.
Abbreviation for Executive control language.
Element (ELT) processor
Processor used to introduce a new element into a program file or to correct the content
of a symbolic element in a program file from a runstream.
7833 1733–004 Glossary–1

Glossary
Exec
The kernel of the OS 2200 system that controls the operating environment. The Exec
process user runs, controls files, manages the system resources, and performs input and
output operations. The active Exec is the Exec that is currently booted. The default
Exec is the Exec to be booted the next time the device is manually selected as the boot
device without explicitly selecting, through the SCF interface, an Exec to boot.
Executive request (ER)
A machine instruction that allows a user to request services from the kernel, or
F
A system call to the OS 2200 Exec that asks the Exec to perform a task (such as I/O) that
is normally privileged and outside the control of the user. The ER is the standard
interface between programs and the operating system, providing programs with access
to system resources under Exec control. Selected ERs affect system security and their
ability to be executed is controlled, or
A program instruction that interrupts the Exec and has it perform a function for the
program. An ER can be used to read or print data, request system information, and
terminate a program. Executive request also refers to the service resulting from the
request.
Fault Location by Interpretive Testing (FLIT)
A tool for development, checkout, installation, and maintenance of software, and for
solving complex debugging problems. FLIT provides a simulated operating environment
where you can run and debug any OS 2200 compatible executable program. Working in
this simulated environment, a programmer can load and execute object code, trace
execution of the code, and change it dynamically without recompiling. Debugging is
controlled by a high-level language (HLL) or low-level language (LLL). Typically, Meta-
Assembler (MASM) programs are debugged using LLL, and PLUS programs are
debugged using HLL. In system mode, you can customize the hardware environment
and boot, run, and debug your own operating system or control program.
FURPUR
The operating system Executive file utility routine. Abbreviation for File Utility
Routines/Program Utility Routines.
Glossary–2 7833 1733–004

M
Glossary
master file directory (MFD)
The file catalog of the Executive that contains Exec file definitions that the system or
users can assign and access. Files listed in the MFD are said to be cataloged and are
retained after a run terminates. In an XTC system, there is a single shared MFD for the
system, and each host has its own standard (local) copy of the MFD. See also standard
MFD, shared MFD, or
P
A directory maintained by the Exec to control cataloged files. The MFD contains the
security attributes for cataloged files. Files listed in the MFD are cataloged and retained
after a run terminates. MFDF$$ is the internal file name that refers to the MFD, or
A list of all the files currently cataloged in the computer system. The file may not
currently be in either main or mass storage, but if cataloged, it will be listed in the MFD
until it is deleted.
post mortem dump processor (PMDP)
A system processor that produces a printout (dump) of the main storage a program
occupied when it terminated. Experienced programmers can use these dumps to
determine what processing occurred. This helps isolate errors in a program.
Programmers Advanced Debugging System
A language-independent interactive debugging tool.
Processor common input/output system (PCIOS)
A system that handles data in conventional PCIOS files.
program control table (PCT)
A special table maintained by the Exec for each active run in the system. The PCT
contains control information about a particular run, and about the program currently being
executed in the run (if any). Among other things, the PCT includes a list of the files
currently assigned to the run, or
A table, one per run, created and maintained by the Exec to accummulate data needed to
control and record each run. The PCT is a read-only user bank from 1 to 42 blocks, or
A bank whose data structure is defined, created, and maintained by the operating
system. The PCT contains information about the run, or
An area in main storage containing the information necessary to define the state of the
program. The PCT shows contents of the P-register, the next instruction to be executed,
and the contents of various data registers. With the information in the program control
table, the Exec can stop the program and resume it exactly where it left off.
7833 1733–004 Glossary–3

Glossary
Problem list entry (PLE)
An organized list of user reported problems, or
R
A unique software problem that has been reported to Unisys and recorded in the
PRIMUS database.
relocatable element
A machine language element produced by a compiler; an object program. Relocatable
elements must still undergo the process of collection before they can be executed. The
system relocatable library has the file name SYS$RLIB$.relocable subroutine library.
S
A component of the operating system that contains useful subroutines you can
incorporate into your programs. Among other things, these subroutines sort and merge
data and perform mathematical and statistical operations.
Software Library Administrator (SOLAR)
A software tool that a site or system administrator uses to install and maintain software
products. SOLAR consists of a set of utilities and the SOLAR processor–a full screen
interface to the utilities.
System data format (SDF)
The standard format used by the Exec to format data for storage in data files. The Exec
system data format is sequential, fixed-block, variable-record length, or
SYSLIB
U
Files that contain only symbolic images (data, directives, or runstreams) in system data
format (SDF). They are commonly used as print files or for data storage. Data files can
be stored on mass storage (disk) or on tape.
Abbreviation for System Service Routines Library, which is a Unisys software product.
Its file name is SYS$LIB$*SYSLIB. It contains system definitions and procedures and
processor interface and utility routines.
Universal Compiling System (UCS)
A system for compiling extended mode programs written in UCS FORTRAN or UCS
COBOL. The UCS compilers produce an absolute element in a standard form that is
called an object module. The UCS and Linking system allow object modules written in
different languages to be linked together as a program. See also object module, OS
2200 linking system, zero overhead object module (ZOOM).
Glossary–4 7833 1733–004

Index
A
Access Methods
common bank, 3-3
relocatable, 3-2
ACD
attributes, 16-12
internal format, 16-12
output, 18-35
Addressing routines, 6-1
AEDIT$
calling sequence, 4-6, 4-7
description, 4-1
error status codes, 4-24
examples, 4-5, 4-13, 4-25
packet format, 4-3
packet generation, 4-4
AEDIT$F
calling sequence, 4-6, 4-16
description, 4-14
error status codes, 4-24
examples, 4-17
AEDIT$SFDT
calling sequence, 4-6, 4-21
error status codes, 4-24
AEDIT$SFDT$
examples, 4-23
ASCII
A$SCTRL procedure, 2-4
conversion table, 9-3
conversion to Fieldata, 9-1
input, 17-33, 23-13
output, 18-35, 23-13, 25-3
Attributed Character Data
attributes, 16-12
internal format, 16-12
output, 18-35
B
BSP$
examples, 5-34
File Control Table, 5-5
functions, 5-1
7833 1733–004 Index–1
C
CABSAD$, 6-1, 6-2
CAINIT$, 6-4
Calling Sequences
auto switch, 3-5
common bank, 3-3
relocatable, 3-2
CBX$, 6-5
common bank routines, 3-1
Common Banks, 3-1
CRELAD$
calling, 6-8
CBN$, 6-13
CRELAD$, 6-9
CRINIT$, 6-12
CSN$, 6-14
description, 6-1
CSX$, 6-6
CSYMVL$, 6-7
CYCLIM$, 2-8
D
Debugging routines
CABSAD$, 6-1
CONWRD$, 7-1
CRELAD$, 6-1
Diagnostic routines
CABSAD$, 6-1
CRELAD$, 6-1
E
Editing
ASCII characters, 4-1
dates, 4-18, 8-8, 22-1

Index
Fieldata characters, 8-1
floating point numbers, 8-9
times, 4-18, 8-8, 22-1
Editing routines
AEDIT$F, 4-14
AEDIT$T, 4-18
EDIT$, 8-1
EDIT$F, 8-9
EDIT$T, 8-8
element subtypes, 2-4
Error status codes
AEDIT$, 4-24
CABSAD$, 6-4
CAINIT$, 6-5
CBN$, 6-13
CBX$, 6-6
CLOSR$ (SIR$), 23-19
CRELAD$, 6-11
CRINIT$, 6-13
CSN$, 6-14
CSX$, 6-7
CSYMVL$, 6-8
entry look_up (BSP$), 5-19
EROR$, 15-6
GETPSF$, 10-4
ID$, 11-6
INISR$ (SIR$), 23-11
item add (BSP$), 5-24
item delete (BSP$), 5-15
item search (BSP$), 5-12
MFDSP$, 13-5
OPNSR$ (SIR$), 23-11
POSTPR$, 14-14
PREPRO$, 14-2
read table (SP$), 5-10
REPRM$, 14-8
REPRO$, 14-8
RINF$, 12-5
ROR$, 15-2
SAR$ ATREAD, 19-23
SAR$ COM, 20-19
SAR$ READ, 17-30
SAR$ WRITE, 18-19
SDFI, 21-18
SDFO, 21-18
SELT$, 12-11
SFDT$, 22-6, 22-11
SINF$, 12-7
SOR, 25-2
SROR$, 15-2
TBLWR$, 15-7
write FTI (BSP$), 5-33
write last item (BSP$), 5-30, 5-31
write table (BSP$), 5-32
Index–2 7833 1733–004
F
Fieldata
conversion table, 9-3
editing, 8-1
input, 17-33, 23-13
File Information Packet
fields (PLUS), 16-2
File Table Index
format, 5-5
reading, 5-4
G
GETPSF$
description, 10-1
error status codes, 10-4
examples, 10-5
MASM calling sequence, 10-2
I
I/O routines, 21-1
ID$
error status codes, 11-6
examples, 11-4, 11-7, 11-11
MASM calling sequence, 11-5
MASM packet format, 11-12
PLUS calling sequence, 11-8
PLUS packet, 11-8
INFOR
format, G-3
reading the table, G-9
subfield number, G-2
table conventions, G-7
table size, G-9
INFOR$
description, 12-1
DUSE$, 12-11
guidelines, 12-2
RINF$, 12-4
SELT$, 12-8
SINF$, 12-6

K
Kanji
input, 17-34
internal format, 16-12
output, 18-35
M
MFDSP$
calling sequence, 13-2
error status codes, 13-5
examples, 13-9
function codes, 13-3
information returned, 13-4
packet, 13-1
N
Nonsupported routines
AEDIT$T, 4-18
EDIT$, 8-1
EDIT$F, 8-9
P
PARTBL
description, 14-5
format, 14-3
PLUS callable routines
CONWRD$, 7-1
ID$, 11-1
SAR$, 16-1
SFDT$, 22-1
Processor Interface Routines, 14-1
Processors
call statement, 12-1
field release, 14-14
field retrieval, 14-10
file assignments, 14-3
Program File
adding items, 5-23
deleting items, 5-14
file table index, 5-5
Searching for, 5-11
searching for items, 5-18
Index
7833 1733–004 Index–3
R
Read routines
SDFI, 21-1
ROR
description, 15-1
EROR$, 15-6
external reference item, 15-5
large location counter item, 15-5
location counter item, 15-4
optimization, 15-7
ROR$, 15-2
SROR$, 15-1
SROR$EB, 15-2
TBLWR$, 15-6
RPCTA$, 2-8
S
SAR$
attribute table entry, 16-12, 17-11, 18-11
attributes, 16-12
character sets, 17-33, 18-34
description, 16-1
error, 19-11
error status, 18-32
error status codes
(ATREAD), 19-23
(COM), 20-9, 20-19
(READ), 17-17, 17-30
(WRITE), 18-19
examples, 17-16, 18-18
file information packet
about, 16-2
MASM
ATREAD function, 19-13
COM function, 20-11
WRITE function, 18-21
PLUS
ATREAD function, 19-1
COM function, 20-1
READ function, 17-1
SAR$ ATREAD$G
MASM interface, 19-1
PLUS interface, 19-13
SDFI
close call, 21-10
description, 21-1
error status codes, 21-18
open call, 21-7
packet format, 21-3

Index
read call, 21-8
SDFO
close call, 21-17
description, 21-1
error status codes, 21-18
open call, 21-16
packet format, 21-11
write call, 21-17
SFDT$
error status codes, 22-6, 22-11
examples, 22-7, 22-12
MASM calling sequence, 22-5
MASM packet format, 22-3
PLUS calling sequence, 22-11
PLUS packet format, 22-8
SIR$
close call, 23-19
description, 23-1
entry points, 23-10
get, 23-18
get image call, 23-13
open call, 23-10, 23-11
options, 23-6
SNOOPY
calling sequence, 24-3
commands, 24-8
control flags, 24-18
demand mode, 24-5
description, 24-1
SYS$DEF System Standard Definitions
PCTBD$, 2-8
PFAPT$, 2-8
PFCPT$, 2-8
PFEPT$, 2-8
PFET$, 2-8
PFFPT$, 2-8
PFTEXT$, 2-8
W
Write routines
SDFO, 21-1
Index–4 7833 1733–004

*78331733-004*
78331733–004