(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.1. Packet............................................................................ 11–2 


11.1.3. Examples ....................................................................... 11–7 

11.2. PLUS Interface ....................................................................... 11–8 

11.2.1. Packet............................................................................ 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.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.1. Packet............................................................................ 22–3 


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 



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 




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


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


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


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


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


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


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


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


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


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 


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


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 


3–4 7833 1733–004


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


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 


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


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 


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


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. 


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


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


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


Table 4–2. AEDIT$: General Purpose ASCII Editing Routines 


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




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




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


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 ‘


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


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


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 


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 



A$EFLG1 x*/6+y,p LA A1,p 


LMJ X11,AEFLG1$ 

A$EFLG2 x*/6+y,p DL A1,p 


LMJ X11,AEFLG2$ 

A$EFLS1 x*/6+y,p LA A1,p 


LMJ X11,AEFLS1$ 

A$EFLS2 x*/6+y,p DL A1,p 


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 


The following example shows a MASM program that generates an ASCII string 

containing floating-point numbers with the common bank version of AEDIT$. 

$ASCII 


$(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’ ‘


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$ 


LA A0,p1 


ER TDATE$ 


LA A0,p1 


ER TDATE$ 


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. 


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. 


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 


Table 4–4. AEDIT$T: ASCII Time and Date Editing Routines 

Generated 

Instructions 

LA A0,p1 


ER TDATE$ 


LA A0,p1 


ER TDATE$ 


LA A0,p1 

LMJ X11,AETIME$ 

ER TDATE$ 

LMJ X11,AETIME$ 

Description 


yearmmdd 

where year is the 4-digit year, and mm and dd are the 2 digits of 

the month and day, respectively. 


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


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 


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


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 


The following example shows a MASM program that creates an ASCII string with date 

and time formats using the relocatable version of AEDIT$. 

$ASCII 


$(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


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



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’ 


A$ECHAR *TAG,X6,S5 LA,S5 A0,*TAG,X6 


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 


A$ECOPY 50,TAB,X6,W LA A0,TAB,X6 

LA,U A1,50 


A$ECOPY COUNT LA,U A1,COUNT 


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 


A$EFLF1 20*/6+9 LA,U A0,20*/6+9 


7833 1733–004 4–25


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$ 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: 


Auto Switch 

L,U A0,address-of-FCT 

LMJ X11,CBRFTI$-1 

error return 

normal return 

Common Bank or 

Relocatable 


I$BJ X11,CBRFTI$ 

error return 

normal return 

Relocatable 


LMJ X11,RFTI$ 

error return 

normal return 

7833 1733–004 5–3


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


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


The following describes the RFTI$$ function: 

Calling sequence 

Auto Switch 


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 


Relocatable 


A1(BSP$-int-level, lengthof-FCT) 

L,U A2,[large-elt text++]sizeindicator 

I$BJ X11,CBRFTI$$ 

error return 

normal return 

Relocatable 


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 


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 


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


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$$ 


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 


Auto Switch Common Bank or 

Relocatable 


L A1,(buffer, length) 

LMJ X11,CBRPFxxT$-1 

error return 

normal return 


L A1,(buffer, length) 

I$BJ X11,CBRPFxxT$ 

error return 

normal return 

Relocatable 


L,U A1,(buffer, length) 

LMJ X11,RPFxxT$ 

error return 

normal return 

7833 1733–004 5–9


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 


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 


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 


Auto Switch 


L,U A1,address-of-searchpacket 

LMJ X11,CBxxIS$-1 

error or no find 

normal return 

Returns 

error return 


04 

Illegal pointer link 


Relocatable 



I$BJ X11,CBxxIS$ 


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 



LMJ X11,xxIS$ 


normal return 

7833 1733–004 5–11


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 


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


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


• 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



Auto Switch Common Bank or Relocatable Relocatable 


L,U A1,address-of-deletepacket 

LMJ X11,CBxxID$-1 

error return or no find 

return 

normal return 

Returns 

error return 


04 

012 

022 




I$BJ X11,CBxxID$ 


return 

normal return 

Registers returned when A0 = 04: 

A1 = address of delete packet 


A3 = address of table descriptor 



FTI not in main storage 

Designated table not in main storage 

7700000000xx 




LMJ X11,xxID$ 


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


no find return 


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


• Assembler, FORTRAN, or PLUS Procedure Table Item Delete Packet 

0 35 


1 

3 zeros 

4 zeros 

• COBOL Procedure Table Item Delete Packet 

0 1 35 


1 

2 zeros 

3 0 C 

I 


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 


1 

2 zeros 

3 zeros 

7833 1733–004 5–17


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 


Auto Switch 


L,U A1,sequence-number 

LMJ X11,CBxxNL$-1 

error return 

normal return 

Returns 

error return 


04 

012 

014 

022 

Sequence number not in table 



Relocatable 



I$BJ X11,CBxxNL$ 

error return 

normal return 

Sequence number is out of range 

Table not in main storage 

7700000000xx 


Relocatable 

L,,U A0,address-of-FCT 


LMJ X11,xxNL$ 

error return 

normal return 

5–18 7833 1733–004

A1 = sequence number 

A2 = number of entries in table 

normal return 


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


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 A1,(CPTBL,252) . Get address, length of buffer 

LMJ X11,RPFCPT$ . Read COBOL procedure table 


. 

L,U X1,CPTBL . Get address of buffer for CPTNUM 

LA,U A7,0 . Initialize loop counter to zero 

LOOP . 


AA,U A7,1 . Increment loop counter 

L A1,A7 . Set sequence number 

LMJ X11,CPTNL$ . Get COBOL item for sequence number 


. 

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 


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 


Auto Switch 



L,U A2,address-of-new-item 

LMJ X11,CBxxIC$-1 

error or no find return 

normal return 


Relocatable 




I$BJ X11,CBxxIC$ 


normal return 

Relocatable 




LMJ X11,xxIC$ 


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) 


004 

012 


No FTI 

7833 1733–004 5–21


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 





no-find return (0,X11) 


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 


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 


Auto Switch 


L,U A1,address-of-addpacket 

LMJ X11,CBxxIC$-1 


normal return 

Returns 

error return 


04 


Registers returned when A0 = 04: 

012 

022 


Relocatable 



I$BJ X11,CBxxIC$ 

error return 

normal return 

A1 = address of packet (search, add, or delete) 


A3 = address of table descriptor 




Designated table not in main storage 

Relocatable 



LMJ X11,xxIC$ 

error return 

normal return 

7833 1733–004 5–23


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 





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


• 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


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 


1 

2 zero 

3 flag-bits type = 5 zero 


5 

6 location of preamble 

7 length of preamble length of relocatable text 



5–26 7833 1733–004


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 


1 

2 zero 


4 version name or blanks 

5 

6 bank informataion 

7 zero length of element text 

8 sector location of element on mass storage 


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 


1 

2 zero 



5 

6 Reserved for use by applications 

7 element 

subtype 

element 

subsubtype 

length of element text 



7833 1733–004 5–27


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 


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 


1 


3 D 

F 

C 

I 

A S K 0 relative word location of the procedure in the file 


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 


0 17 18 35 


1 


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 


Auto Switch 


LMJ X11,CBPTxxWT$-1 

Returns 

error return 

error return 

normal return 


7700000000xx 

012 


Relocatable 


I$BJ X11,CBPTxxWT$ 

error return 

normal return 


No FTI 

Relocatable 


LMJ X11,PTxxWT$ 

error return 

normal return


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


Auto Switch 


LMJ X11,CBxxIU$-1 

Returns 

error return 

error return 

normal return 


012 

022 

normal return 

FTI not in main storage. 



Relocatable 


I$BJ X11,CBxxIU$ 

Designated table not in main storage. 

error return 

normal return 

Relocatable 


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


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 


Auto Switch 


LMJ X11,CBWPFxx$-1 

error return 

normal return 

Returns 

error return 


012 

022 



Relocatable 


I$BJ X11,CBWPFxx$ 

error return 

normal return 

Relocatable 


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. 


Auto Switch 


LMJ X11,CBWFTI$-1 

error return 

normal return 

Returns 

error return 


042 

043 



Relocatable 


I$BJ X11,CBWFTI$ 

error return 

normal return 

Relocatable 


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


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 


LMJ X11,RFTI$ . Read FTI 


. 


L A1,(ELTTBL,252) . Get addr,len of buffer 

LMJ X11,RPFET$ . Read element table into buffer 


. 


L,U A1,ADDPKT . Get address of add packet 

LMJ X11,ETIA$ . Add the element to the file 


. 

. Write element text, using SDFO (for example) 

. 


LMJ X11,WPFET$ . Write back the element table 


L A7,FCT+7 . Get next write location 

A,U A7,ELTLEN . Add length of new element 

S A7,FCT+7 . Put in FCT 

. 


LMJ X11,WFTI$ . Write back the 


. 

. 

. 

5–34 7833 1733–004


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


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


ο 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


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, 


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. 


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 


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


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. 


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$ 


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. 


C$ABSAD[,t] ‘CBX$’[,bank-name] [pkt-addr] 

error return 

normal return 

Parameters 

t 

See 6.1. 

7833 1733–004 6–5


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. 


C$ABSAD[,t] ‘CSX$’[,seg-name] [pkt-addr] 

error return 

normal return 

6–6 7833 1733–004

Parameters 

t 

CSX$ 

See 6.1. 


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. 


C$ABSAD[,t] ‘CSYMVL$’[,symbol] [pkt-addr] 

error return 

normal return 

Parameters 

t 

See 6.1. 

7833 1733–004 6–7


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. 


C$RELAD[,t] func-code [,p1,p2] [pkt-addr] 

error return 

normal return 

6–8 7833 1733–004

Parameters 

t 


Type of call to the routine. This parameter is optional and may be omitted. CB or A, 


func-code 

p1,p2 




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. 


C$RELAD[,t] ‘CRELAD$’[,abs-addr] [pkt-addr] 

error return 

normal return 

7833 1733–004 6–9


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


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


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. 


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 


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 


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. 


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 


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


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. 


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 


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


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$ is called from PLUS routines by declaring procedures with the appropriate 

entry points. 


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


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. 


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


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


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



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


Instructions 


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


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$ 
















Edits a date (mm/dd/yy). 

number of seconds since midnight 


mm/dd/yy 

where mm, dd, yy are the 2 digits of the month, day, and year, 

respectively. 

Edits a date (dd mmm yy). 


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). 


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). 


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


Table 8–3. Time and Date Editing Routines 

PROC Call Generated Instructions Description 



E$TIME p1 LA A0,p1 

LMJ X11,ETIME$ 

E$TD ER TDATE$ 

LMJ X11,ETIME$ 


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


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 


LMJ X11,EFLF1$ 

E$FLF2 x*/6+y,p DL A1,p 


LMJ X11,EFLF2$ 

E$FLG1 x*/6+y,p LA A1,p 


LMJ X11,EFLG1$ 

E$FLG2 x*/6+y,p DL A1,p 


LMJ X11,EFLG2$ 

E$FLS1 x*/6+y,p LA A1,p 


LMJ X11,EFLS1$ 

E$FLS2 x*/6+y,p DL A1,p 


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. 


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 


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 




I$BJ X11,CBFDASC$ 

normal return 




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 


$(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$ converts ASCII character strings to Fieldata when the ASCFD$ entry point is 

called. 

The following table lists the calling sequences. 





LMJ X11,CBASCFD$-1 

normal return 




I$BJ X11,CBASCFD$ 

normal return 




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


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



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. 


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. 




10–2 7833 1733–004

func-code 


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


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 


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


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


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 


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. 


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. 


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 


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


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



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. 


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, 


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


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



The following example calls the ID$ routine to generate an ASCII identification line. 

$ASCII 


$(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$ 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). 


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. 


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 


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


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); 

. 

. 


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


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). 


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


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


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


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. 


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


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


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 



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, 


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 


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 




common bank version of the SINF$ routine is being called and this parameter is 



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


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, 





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 


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 




common bank version of the SELT$ routine is being called and this parameter is 



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


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


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, 





I$NFOR[,t] ‘DUSE$’[,use-name] [packet] 

return 

7833 1733–004 12–11


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 


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. 



common bank version of the INFOR$ routines is being called and this parameter is 



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 


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. 


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 


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


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 


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


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. 


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. 



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. 



Garbage lead item. A lead item was found that contained invalid links to all main 

items. 

7833 1733–004 13–7


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. 



13–8 7833 1733–004

13.4. Examples 


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


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. 



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


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.) 



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


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. 


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


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. 


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


Figure 14–1. PARTBL Table Format 

14–4 7833 1733–004

14.1.3. PARTBL Description 


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


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 


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


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. 


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. 


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


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. 


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. 


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


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. 


FLDGETO$ and FLDGETM$ require PARTBL as defined for PREPRO and PREPRM, 

respectively. 


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 


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


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


PREPF$ generates the source input and source output fields of PARTBL (see Figure 

14–1). 


PARTBL must be externally defined, and at least 27 decimal words in length, and should 

be zero-filled. 


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


14.3. POSTPR$–Postprocessor Routine 

POSTPR$ removes all changes in the assignment status of a file that PREPRO, 

PREPRM, or PREPF$ made. 


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$. 


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. 


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


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. 


L,U A0,address-of-item 

LMJ X11,ROR$ (or ROR$EB) 

error return 

normal return 

Error Return 


• 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 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


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


• 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


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. 


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


L,U A0,preamble-addr 

L,U A1,preamble-length 

LMJ X11,TBLWR$ (or TBLWR$EB) 

error return 

normal return 

Error Return 



• 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


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


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 


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 


The source language type of the PROC to be read 


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 


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 


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 


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


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 


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 


The address of the buffer containing the output version name. The version name 


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 


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 


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 



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 


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 


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 


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 


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 


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


NEXT_WRITE_LOCATION 


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, 


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 


ACCESS_TYPE 



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 


• Fields required for WRITE 




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 


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 


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). 


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 


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


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 


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 


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 


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


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 


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


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 


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.


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. 



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 


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 


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 


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 


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 


The length in words of the input image buffer. 

17–2 7833 1733–004

TEXT_BUFFER_ADDRESS: 


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 


The length in 9-bit bytes of the input text buffer. 

ATTRIBUTE_TABLE_ADDRESS 


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 


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 


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 


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 


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 


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 


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 


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 


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 


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 


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 


This field contains additional information for particular CALL_STATUS codes. 

IO_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 


A one-word combination of CALL_STATUS, SUB_STATUS, and IO_STATUS 

contained in H2, T1, and S3, respectively. 

SYMB_STATUS_WORD 


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 


The recommended buffer or table size when an invalid length is specified or when 

an overflow occurs. 

TEXT_LENGTH_IN_BYTES 


The length in 9-bit bytes of the character text returned in the text buffer. 

NUMBER_OF_ATTRIBUTES 


The number of attributes returned in the attribute table. 

CHARACTER_TYPE 


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 



INPUT_CHARACTER_CODE 


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 


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 


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 


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 


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 


The type of control record read (an octal code from 040 to 077). 

7833 1733–004 17–9

SAR$ READ 

CONTROL_RECORD_WORD_LENGTH 


The length in words of the control record read. 

CONTROL_RECORD_CHAR_TYPE 


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 


The length in words of the data record read. 

DATA_RECORD_CHAR_TYPE 


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. 


0 17 18 26 27 35 


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. 


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) 


INPUT_FILE_INFO_PKT_ADDRESS 

INPUT_BUFFER_ADDRESS 

INPUT_BUFFER_WORD_LENGTH 



• Optional parameters (described in 17.1.1.2) 



REQUEST_TYPE 

LINE_NUMBER_FORMAT 


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. 


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. 



values before calling SAR_READ: 


TEXT_BUFFER_ADDRESS 







READ_ADDRESS_SECTOR 

READ_ADDRESS_WORD_OFFSET 


PROCEDURE SAR_READ 


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. 


PROCEDURE SAR_CLOSE_INPUT 


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 


RETURN; 

END; 

ENDCASE; 

END; 

. 

. 

. 

SAR_CLOSE_INPUT(LOC(READ_PKT)); 

IF READ_PKT.CALL_STATUS NE S ‘Normal’ 

THEN BEGIN 


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 


0 Normal return from SAR$. 

01 End-of-file condition reached by SAR_READ. 

7833 1733–004 17–17

SAR$ READ 



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



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 


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 


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 


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 


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 



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 


SR$TEXTLEN 


SR$NUMATTR 


SR$CHARTYP 

The character set type of the image returned to the caller: 

0 Fieldata 6-bit characters 




If SR$UNTRFLG is zero (untranslate mode off), then any Fieldata images read are 



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 


SR$LNUMF3 

The third 10 digits of the fractional part of a fractional line number. This field is 


SR$LNUMF4 

The fourth 10 digits of the fractional part of a fractional line number. This field is 


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. 


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 


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. 



values before calling S$AROPENI: 


SR$PKTVER 

SR$INPBUFL 

SR$FIPADDR 

SR$IMGBUF 

SR$INPBUF 

SR$IMGBUFL 


SR$SELLST 

SR$UNTRFLG 

SR$SELLSTL 

SR$LNUMFMT 

SR$REQTYPE 

SR$SDFCNTL 


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 


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. 



values before calling S$ARREAD: 


SR$TEXBUF 

SR$ATTRIBL 

SR$TEXBUFL 

SR$ATTRIB 


SR$ADDRSEC 

SR$SELLSTL 

SR$ADDRWO 

SR$SELLST 


S$ARREAD rpkt 

error return 

end-of-file return 

normal return 


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 




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. 


S$ARCLOSI rpkt 

error return 

normal return 


Returns 

If the error return from S$ARCLOSI is taken, A1 contains the call status code, A2 




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 



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



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. 



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. 


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 


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 



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. 


code is returned in T1 of the SR$STATUS field. 


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. 


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: 



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 


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 


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 


The length in words of the output buffer. It must be of length 28 * dpf * n, where 


output is to an SDF file or element. It is omitted if output is to a symbiont file. 

18–2 7833 1733–004



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. 



The length in words of the output image buffer. 



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. 



The length in 9-bit bytes of the character text in the text buffer. 



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. 



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 


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 


OUTPUT_FILE_TYPE 


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 


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 


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 


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). 


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 


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. 




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 


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 


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 


For symbiont file output, the number of lines to space before printing the image 

(default is 1). 

ELEMENT_CREATION_DATE_AND_TIME 


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 



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) 


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 


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 


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 


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. 




IO_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 



contained in H2, T1, and S3, respectively. 



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 




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. 



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. 



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 


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, 


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. 


0 17 18 26 27 35 


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 


Table 18–1. SAR$: PLUS WRITE Buffer and Table 








Table 18–2. SAR$: PLUS WRITE Buffer and Table 

Type Definitions 








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. 


The calling program sets the following parameters in the WRITE packet to appropriate 

values before calling SAR_OPEN_OUTPUT: 



OUTPUT_FILE_INFO_PACKET_ADDRESS 

OUTPUT_BUFFER_ADDRESS 

OUTPUT_BUFFER_WORD_LENGTH 




OUTPUT_FILE_TYPE 

OUTPUT_LINE_NUMBER_TYPE 

OUTPUT_IMAGE_CHARACTER_TYPE 


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. 


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. 



values before calling SAR_WRITE: 







OUTPUT_RECORD_TYPE 

INPUT_TEXT_CHARACTER_TYPE 



LINE_NUMBER_FRACTIONAL_PART(1:4) 


PROCEDURE SAR_WRITE 


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 



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 



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 


PROCEDURE SAR_WRITE_CONTROL 


IMPORTED ('SAR$WCNTL$PG'); 

Parameters 

CONTROL_FUNCTION 


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 


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 


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 


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 


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 


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. 


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. 


PROCEDURE SAR_CLOSE_OUTPUT 


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 


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 


RETURN; 

END; 

. 

. 

. 

SAR_CLOSE_OUPUT(LOC(WRITE_PKT)); 

IF WRITE_PKT.CALL_STATUS NE S ‘Normal’ 

THEN BEGIN 


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 



01 An outdated WRITE packet version is being used. 

02 An invalid WRITE packet version is being used. 


given for the output image buffer. 


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 



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. 


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 


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 


032 The file name buffer address in the FIP is NULL; an address of a symbiont file 


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



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 






0103 An incorrect SDFO packet version is being used. The correct SDFO packet 




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 



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 



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 


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 


to be written out. Subsection 15.6.2 describes the text buffer. 

SW$TEXBUFL 


SW$ATTRIB 

The address of the output attribute table into which the caller places the attributes 


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 


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. 


Other character set types may not be written out by SAR$. See 18.3 for details on 


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 


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 


SW$LNUMF3 

The third 10 digits of the fractional line number to be written out with the output 


SW$LNUMF4 

The fourth 10 digits of the fractional line number to be written out with the output 


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 



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. 


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 


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 


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. 



values before calling S$AROPENO: 


SW$PKTVER 

SW$OUTBUFL 

W$FIPADDR 

W$IMGBUF 

W$OUTBUF 

W$IMGBUFL 

7833 1733–004 18–29

SAR$ WRITE 


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 



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, 


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. 



values before calling S$ARWRITE: 


SW$TEXBUF 

SW$ATTRIBL 

SW$TEXBUFL 

SW$ATTRIB 

18–30 7833 1733–004


SW$OUTRECT 

SW$LNUMINT 

SW$LNUMF3 

SW$ICHART 

SW$LNUMF1 

SW$LNUMF4 

SW$LINESPA 

SW$LNUMF2 


S$ARWRITE wpkt 

error return 

normal return 

SAR$ WRITE 


Returns 

If S$ARWRITE takes the error return, A1 contains the call status code, A2 contains the 




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 


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. 


S$ARCLOSO wpkt 

error return 

normal return 


Returns 

If S$ARCLOSO takes the error return, A1 contains the call status code, A2 contains the 




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 



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



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. 


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 


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 


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 


032 The file name buffer address in the FIP is zero; an address of a symbiont file 


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 



0100 An unrecognized error has occurred in the SDFO routine. The SDFO error 






0103 An incorrect SDFO packet version is being used. The correct SDFO packet 




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 



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: 


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: 


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: 


The length in words of the image buffer. 

OUTPUT_TEXT_BUFFER_ADDRESS: 


The address of the output text buffer into which the caller places the character text 

to be written out. 

OUTPUT_TEXT_BUFFER_BYTE_LENGTH: 



OUTPUT_ATTRIBUTE_TABLE_ADDRESS: 




OUTPUT_ATTRIBUTE_TABLE_WORD_LENGTH is zero. 

19–2 7833 1733–004

OUTPUT_ATTRIBUTE_TABLE_WORD_LENGTH: 


SAR$ ATREAD 



INPUT_TEXT_BUFFER_ADDRESS: 


The address of the input text buffer into which ATREAD places the character text of 

the image read. 

INPUT_TEXT_BUFFER_BYTE_LENGTH: 



INPUT_ATTRIBUTE_TABLE_ADDRESS: 


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: 


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 


OUTPUT_CHARACTER_TYPE 


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). 


7833 1733–004 19–3

SAR$ ATREAD 

Other character set types may not be written out by SAR$. See18.3 for details on 




The number of lines to space before writing the image (default is 1). 

INPUT_SELECT_LIST_ADDRESS 


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 


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 





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 


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 


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. 




IO_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 



contained in H2, S1, and S3, respectively. 



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. 





7833 1733–004 19–5

SAR$ ATREAD 

OUTPUT_IMAGE_BYTE_LENGTH 


The length in bytes of the image written out by SAR_ATREAD. 

BYTE_LENGTH_OF_INPUT_TEXT 


The length in 9-bit bytes of the character text returned in the input text buffer. 

NUMBER_OF_INPUT_ATTRIBUTES 


The number of attributes returned in the input attribute table. 

INPUT_CHARACTER_TYPE 


The character set type of the image read: 

S'ASCII_ISO' ASCII/ISO 9-bit characters 



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 






If a Fieldata image is read, it is translated to ASCII/ISO before being returned to the 


19–6 7833 1733–004

19.1.2. PLUS ATREAD Procedures Buffers and Tables 

SAR$ ATREAD 


the buffers and tables, and definitions for the default buffer and table lengths, are 


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. 


Table 19–1. SAR$: PLUS ATREAD Buffer and Table 









Table 19–2. SAR$: PLUS ATREAD Buffer and Table 

Type Definitions 








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. 


The calling program sets the following parameters in the ATREAD packet to appropriate 

values before calling SAR_INITIALIZE_ATREAD: 







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. 


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. 


The calling program sets the following parameters in the packet to appropriate values 

before calling SAR_ATREAD: 


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 





PROCEDURE SAR_ATREAD 


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: 


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 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 


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. 


PROCEDURE SAR_RESTORE_ATREAD 


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 


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 


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. 



7833 1733–004 19–11

SAR$ ATREAD 

Table 19–3. SAR$: ATREAD Procedure CALL_STATUS Codes 




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. 


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. 



027 A partial image was read by SYMB$. 








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 



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 



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 


to be written out. 

SA$OTEXTBL 


SA$OATTRT 


describing the character text to be written out. This field is undefined if the output 

attribute table word length is zero. 

SA$OATTRTL 



SA$ITEXTB 

The address of the input text buffer into which ATREAD places the character text of 

the image read. 

SA$ITEXTBL 


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 


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 


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. 


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 


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 


0 

1 

SA$PCW 

Do not search for embedded shift-coded kanji in ASCII/ISO (default) 


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 



SA$OIMGLEN 

The length in bytes of the image written out by ATREAD. 

SA$TEXTLEN 


SA$NUMATTR 


19–16 7833 1733–004

SA$ICHART 





SAR$ ATREAD 

If a Fieldata image is read, it is translated to ASCII/ISO before it is returned to the 


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. 


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 


The B-register to be attached to the ATREAD packet EQUFs. If it is omitted, no 


A flag to display a table of the ATREAD packet EQUFs. If it is set to 'D', the field 


Example 

$ASCII 


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. 


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 


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. 



values before calling S$ARINITATR: 


SA$PKTVER 

SA$IMGBUF 

SA$IMGBUFL 

7833 1733–004 19–19

SAR$ ATREAD 


SA$ISLIST 

SA$ISLISTL 

SA$REQTYPE 

SA$PCW 

Note: It is recommended that the calling program zero-fill the ATREAD packet before 



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 


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. 



values before calling S$ARATREAD: 


SA$OTEXTB 

SA$OATTRTL 

SA$IATTRT 

SA$OTEXTBL 

SA$ITEXTB 

SA$IATTRTL 

SA$OATTRT 

SA$ITEXTBL 

19–20 7833 1733–004


SA$OCHART 

SA$LINESPA 


S$ARATREAD atrpkt 

error 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, 


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: 



returned in the fields SA$ITEXTB and SA$TEXTLEN, respectively. 


The character set type of the image read is returned in the field SA$ICHART. 



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 


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. 



SA$RECBUFL. 



returned in the field SA$RECBUFL. 



the field SA$RECBUFL. 



7833 1733–004 19–23

SAR$ ATREAD 

Table 19–6. SAR$: ATREAD Procedure SA$CALLST Status Codes 








027 A partial image was read by SYMB$. 


code is returned in the SA$SUBSTAT field. 


error code is returned in the SA$SUBSTAT field. 


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 


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: 



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 



The address of the output text buffer, which contains the character text of the image 

that the SAR$ COM function writes out. 



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. 



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. 



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. 



The character set type of the image written out by the SAR$ COM function. 

S'ASCII_ISO' ASCII/ISO 9-bit characters (default). 


20–2 7833 1733–004


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. 



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. 



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). 



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. 




of zero indicates there is no output attribute table (default). 



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 




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 




to return to the caller. The default is no input select list. 



The length in 9-bit bytes of the input select list. A length of zero indicates there is no 

input select list (default). 



The request type for the input image. 


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 


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. 




See the ER COM$ section, Exec ER Programming Reference Manual for further 

details. 

20–4 7833 1733–004

CONTROL_BITS 


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 


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, 


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 


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 


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. 




COM_STATUS_WORD 


A one-word combination of CALL_STATUS and SUB_STATUS contained in H2 and 

S1, respectively. 



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 


The length in bytes of the image written out by the SAR_COM procedure. 

BYTE_LENGTH_OF_INPUT_TEXT 


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 



20–6 7833 1733–004

20.1.2. SAR$ PLUS COM Procedure Buffers and Tables 

SAR$ COM 


the buffers and tables and the definitions for the default buffer and table lengths are 


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. 


Table 20–1. SAR$: PLUS COM Buffer and Table Length 

Defaults 







Table 20–2. SAR$: PLUS COM Buffer and Table Type Definitions 







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 


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. 


The calling program sets the following parameters in the packet to appropriate values 

before calling SAR_COM: 


















CONSOLE_CLASS 

CONTROL_BITS 

ADDITIONAL_CONTROL_BITS 

RUN_ID_FOR_LOGGING 

ROUTING_CONSOLE 

ROUTING_INFORMATION 

20–8 7833 1733–004


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: 


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. 


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 


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 


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. 





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 



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. 



RECOMMENDED_BUFFER_LENGTH. 



returned in the field RECOMMENDED_BUFFER_LENGTH. 



the field RECOMMENDED_BUFFER_LENGTH. 









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$. 



0101 An unrecognized error has occurred in executing ER COM$. The COM$ 



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 


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 


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. 


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 


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 


SC$IATTRTL 


is no input attribute table (default). 

20–12 7833 1733–004

SC$ISLIST 

SAR$ COM 


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, 


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 


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. 


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 


The B-register that is attached to the COM packet EQUFs. If it is omitted, no 


A flag that displays a table of the COM packet EQUFs. If it is set to 'D', the field 


7833 1733–004 20–15

SAR$ COM 

Example 

$ASCII 


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. 


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. 


The calling program sets the following parameters in the COM packet to appropriate 

values before calling the S$ARCOM PROC: 


SC$PKTVER 

SC$ITEXTB 

SC$OTEXTB 

SC$ITEXTBL 

SC$OTEXTBL 

7833 1733–004 20–17

SAR$ COM 


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 


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: 



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. 



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 


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 


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. 


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


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


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


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


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


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. 


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


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$ 


L,U A0,address-of-packet 

LMJ X11,CBSDFIO$-1 

error return 

normal return 

Calling Sequence for SDFIOA$ 


I$BJ X11,CBSDFIO$ 

error return 

normal return 


LMJ X11,SDFIO$ 

error return 

normal return 



L A1,word-offset 

LMJ X11,CBSDFIOA$-1 

error return 

normal return 



I$BJ X11,CBSDFIOA$ 

error return 

normal return 



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


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$ 



LMJ X11,CBSDFI$-1 

error return 


normal return 

Calling Sequence for SDFINT$ 


I$BJ X11,CBSDFI$ 

error return 


normal return 


LMJ X11,SDFI$ 

error return 


normal return 



LMJ X11,CBSDFINT$-1 

error return 


normal return 


I$BJ X11,CBSDFINT$ 

error return 


normal return 


LMJ X11,SDFINT$ 

error return 


normal return 

Returns 

If SDFI takes the error return, register A4 contains the error code. See 21.3 for an 


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


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$ 



LMJ X11,CBSDFIC$-1 

normal return 


I$BJ X11,CBSDFIC$ 

normal return 


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. 


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 


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


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 


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


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 


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



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$ 



LMJ X11,CBSDFOO$-1 

normal return 

Calling Sequence for SDFOOSF$ 


I$BJ X11,CBSDFOO$ 

normal return 


LMJ X11,SDFOO$ 

normal return 



LMJ X11,CBSDFOOSF$-1 

normal return 


I$BJ X11,CBSDFOOSF$ 

normal return 


LMJ X11,SDFOOSF$ 

normal return 

21–16 7833 1733–004

21.2.2.2. Write an Image 


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$ 


Relocatable 


LMJ X11,CBSDFO$-1 

error return 

normal return 


I$BJ X11,CBSDFO$ 

error return 

normal return 

Relocatable 


LMJ X11,SDFO$ 

error return 

normal return 

If SDFO takes the error return, register A4 contains the error code. See 21.3 for an 


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$ 


Relocatable 


LMJ X11,CBSDFOC$-1 

error return 

normal return 


I$BJ X11,CBSDFOC$ 

error return 

normal return 

Relocatable 


LMJ X11,SDFOC$ 

error return 

normal return 

7833 1733–004 21–17


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 


(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


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. 


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. 


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


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 


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. 


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. 


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, 


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


date 

time 

The address of a caller-specified date and time (must be in TDATE$ format). This 


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



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$ 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. 


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


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


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



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_ERROR_CODE 


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


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


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


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. 


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


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 


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


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 


ASCII-like Translated to 


"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 


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


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 


ASCII or 

ASCII-like 

Translated to 


"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 


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


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


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. 


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. 


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


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


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. 


L A0,(buffer-length,buffer-addr) 

LMJ X11,GETAS$ 

error 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


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) 


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


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. 



LMJ X11,GETSR$ 

error 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. 


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. 


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


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. 



LMJ X11,GETNM$ 

error 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


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. 


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$). 


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


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 


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


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 


• 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


• 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


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) 


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


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 


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


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


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


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) 


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


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


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


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 


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


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 


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


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 


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


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 


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


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 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. 


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


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. 


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


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. 



LMJ X11,SOR$ (or SORA$) 

error return 

normal return 

where: 

image-length 





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


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. 



L,U A1,CCS-identifier 

LMJ X11,SORNM$ (or SORNMA$) 

error return 

normal return 

where: 

image-length 




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. 


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


25.5. ESOR$–End Symbolic Output 

ESOR$ terminates the operations of the SOR routine. 


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


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 


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


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. 


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


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




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



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 


7833 1733–004 D–3




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 




SYS$DEF Absolute (object module) 

SYS$DEF Omnibus 

SYS$DEF Relocatable 0 

TABLE$ Relocatable SYSLIB$3 0200 

D–4 7833 1733–004


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 




7833 1733–004 D–5


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




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




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




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$ 




MFDSP$ MFDSP$ CBMFDSP$ 

E–4 7833 1733–004




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$ 




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


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 


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. 


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


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. 


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


F.2.3. EM$TREADPKT 

The EM$TREADPKT PROC generates the packet for the EM$TREAD and EM$ATREAD 

PROCs. 


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 


The EM$SNAPPKT PROC generates the packet for the EM$SNAP PROC. 


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


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 ‘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


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: 


7833 1733–004 G–3


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 


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


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


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


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 


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 


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 


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 


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


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




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_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_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




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


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


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


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


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 


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 


17, 18 The address of the integer to edit 


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 


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


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. 


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. 


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. 


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


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: 


A2 modifier (bits 18–35). 

• If param1 is specified, even as 0, param2 should also be specified. 


A2 increment (bits 0–17). 

I–6 7833 1733–004


Table I–4 contains the function codes that may be used on the EM$BSP PROC call. 

Table I–4. EM$BSP Function Codes 


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 


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


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. 


The EM$BSPPKT PROC generates the packet for the Extended Mode interface to BSP$. 

This packet is required for the EM$BSP PROC. 


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$ 


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. 


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



The EM$FDASCPKT PROC generates the packet for the Extended Mode interface to 

FDASC$. This packet is required for the EM$%FDASC PROC. 


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. 


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 


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. 


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. 


EM$GETPSFPKT generates the 18-word packet for the Extended Mode interface to 

GETPSF$. This packet is required for the EM$GETPSF PROC. 


label EM$GETPSFPKT 

There are no parameters for the EM$GETPSFPKT PROC. 

7833 1733–004 I–11


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. 


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. 


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$ 


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. 


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 


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 


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


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 


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. 


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. 


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. 


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


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. 


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 


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


Table I–8 contains the function codes that may be used on the EM$MFDSP PROC call. 

Table I–8. EM$MFDSP Function Codes 


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 


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. 


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


label EM$MFDSPPKT [buflen] [filename] 

where: 

buflen 


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


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. 


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. 


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. 


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 


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


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 


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


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 


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 


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


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 


J–8 7833 1733–004

E$TERM(20)–Terminate 


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


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 


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 


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


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 


$(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


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


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$. 


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$ 


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. 


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


date 

time 

the address of a caller-specified date and time (must be in TDATE$ format). This 


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


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 


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




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




SDFO SDFOC$ BSDFOC$ 

SDFOOSF$ BSDFOOSF$ 

SDFOO$ BSDFOO$ 

SDFO$ BSDFO$ 

SFDT$ SFDT$ BSFDT$ 

STARTSFDT$ BSTARTSFDT$ 

7833 1733–004 J–19


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 


OS 1100 Meta-Assembler (MASM) Programming Reference Manual (7830 8269). 


OS 2200 Exec System Software Installation and Configuration Guide (78306 7915). 


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). 


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). 


OS 2200 Service Library Programming Reference Manual (7830 7857). 


OS 2200 System Services Programming Reference Manual (7833 4455). 


7833 1733–004 K–1

Related Product Information 

OS 1100 Exec System Software Executive Request Programming Quick-Reference Guide 


OS 1100 Postmortem Dump (PMD) Programming Reference Manual (UP-8725). 


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 




examples, 4-17 

AEDIT$SFDT 



AEDIT$SFDT$ 


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 



output, 18-35 

B 

BSP$ 


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 


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$ 




MASM calling sequence, 10-2 

I 

I/O routines, 21-1 

ID$ 


examples, 11-4, 11-7, 11-11 


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$ 


DUSE$, 12-11 

guidelines, 12-2 

RINF$, 12-4 

SELT$, 12-8 

SINF$, 12-6

K 

Kanji 

input, 17-34 


output, 18-35 

M 

MFDSP$ 

calling sequence, 13-2 



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 


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 


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 


character sets, 17-33, 18-34 


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 



open call, 21-7 

packet format, 21-3

Index 

read call, 21-8 

SDFO 




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 packet format, 22-3 

PLUS calling sequence, 22-11 

PLUS packet format, 22-8 

SIR$ 



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 


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

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

Create successful ePaper yourself

Delete template?

Save as template?