<<< Back Home >>>

ERPFX$ 1R1D - ER PFx$ to BSP$ Redirection


Go to Table of Contents


1. Introduction

ERPFX$ is a library routine that allows programs using PFx$ Executive Requests (PFWL$, PFS$, PFI$, PFD$, PFUWL$) to be redirected to the SYSLIB routine BSP$ with little modification, thus allowing full support for LPF and LEPF files. The ERs are intercepted and converted to subroutine calls; program files are read and updated as needed transparently to the user; and status registers are returned as with the actual ERs. Provisions are made for banking most of the IBANK and DBANK portions of ERPFX$ so that there will be little size increase to the program.

ERPFX$ consists of the omnibus definition element ERPFX$DEF and the relocatable element ERPFX$/nRnx, which must be available at compile and @MAP time, respectively.


2. Implementation
[Top][Contents]

For a program to use ERPFX$, the following statement must appear at the beginning of every element containing an ER PFx$ call; it may follow other standard $INCLUDEs:

        $INCLUDE  'ERPFX$DEF'

In addition, the following procedure call -- which also needs the above $INCLUDE -- must appear somewhere in the program, preferably in the main data area, although the proc will always revert to the location counter in effect on entry after generating its data.

        ERPFX$SETUP[,'CB']  [Nfiles,Ntrks,RtnReg]  [MainLC,BulkLC,BulkBDR]

where:

'CB' -   If present, calls to BSP$ routines are common banked vs. relocatable. If 'CB' is used, the program must follow the convention that all data to be accessed by BSP$ must be based and above 040000 when BSP$ is called; and only the main IBANK and other unbased IBANKs may overlap it from 01000-040000.

Nfiles - The maximum number of files for which ER PFx$ calls are processed. Default: 2. The PFx$ ERs only deal with internal filenames which are assumed to be assigned, so this number represents the number of distinct internal filenames to be used with ERPFX$.

Ntrks  - The number of memory tracks (1792 words each) to reserve for each file's element table, in addition to the pointer table. Default: 1.

Because BSP$ deals with the element table in pages, the default size is enough to handle any size program file and there is no danger of overflow. However, increasing Ntrks can improve efficiency.

RtnReg - If present, the register to use when returning from ERPFX$. This is only required if multiple activities in the program will perform ER PFx$s. RtnReg may be X1-X11, A0, or A3. (A1 and A2 are used to return information and status.)

If omitted, ERPFX$ will return using an indirect jump. ERPFX$ performs all its functions with the data area locked out, but it must unlock it just before the return, which could leave a small window if multiple activities are involved; hence the need for RtnReg.

MainLC - The location counter under which to generate the program's basic data area for ERPFX$ interface, about 33 words. Default: 60.

This location counter must be collected so as to be based whenever an ER PFx$ is performed, and must be located under the 65K (200000 octal) boundary.

BulkLC - The location counter under which to generate the bulk of the data used for ERPFX$ and BSP$ interface. Default: 62. This area's size is 23+Nfiles*(Ntrks*1792+196) words and includes each file's FCT, FTI, and element table area.

This location counter may be placed either in the program's main DBANK, if there is room, or in a parallel DBANK starting at the same address. ERPFX$ will switch banks as needed, since this area must be based and available whenever BSP$ is called. It must also be based simultaneously with ERPFX$'s $(3), whether in the same or a different bank. It may be located above the 65K (200000 octal) boundary.

BulkBDR - If present, the BDR on which to base the bulk data for ERPFX$. Default: 2 (Main DBANK). This is intended for the case where the bulk data is in an unbased bank parallel to some other bank that is based on a BDR other than the main DBANK at the time of the call. If BulkBDR is -1, this will signal ERPFX$ to obtain the BDR for the bulk data from the value coded in the second subfield of the second field of the DBANK statement for this bank,

Example: 'DBANK PFXDBANK ,3'

The relocatable element ERPFX$/nRnx must be LIB'd or explicitly collected with the program. It has two IBANK location counters: $(1) (21 words), which must be collected so as to be based at the time of the call, preferably in the main IBANK; and $(3) (194 words), which may be in the same or a different bank and need not be based at the time of call. If based, however, it must not displace either of ERPFX$'s data areas, or any data which may be passed to BSP$, namely the PFS$ packet. ERPFX$ will base this bank as needed, using the main IBANK BDR by default unless an alternate BDR is coded in the second subfield of the second field of the bank's IBANK statement.

Example: 'IBANK PFXIBANK ,1'

If BSP$ is called as a relocatable as opposed to a common bank, its instruction and data areas must both be based at the time ERPFX$ calls it, which means at the time $(3) of ERPFX$ is based. This may mean collecting its odd and even location counters in the same bank as $(3) of ERPFX$, or in one or two banks that will be based at the time $(3) of ERPFX$ is based.

The sequence below illustrates which IBANK and DBANK areas need to be based at the same time during the steps of a typical call to ERPFX$:

   1. ERPFX$($1) - MainLC - User's PFS$ packet
   2. ERPFX$($3) - MainLC - User's PFS$ packet
   3. ERPFX$($3) - BulkLC
   4. BSP$       - BulkLC
   5. ERPFX$($3) - BulkLC
   6. ERPFX$($3) - MainLC - User's PFS$ packet
   7. ERPFX$($1) - MainLC - User's PFS$ packet

3. Operation [Top][Contents]

The following is a description of the default operation of each intercepted PFx$ ER. In all cases, A0 is loaded with the address of the program file packet: a two-word internal filename, usually followed by a 6- or 10-word element entry. (Each LA A0 instruction in the descriptions shows how many words are expected.) In two cases A1 is loaded with an updated write location.


3.1. PFWL$ - Obtain Next Write Location
[Top][Contents]
        LA,U A0,PFPKT       . (2)
        ER   PFWL$

1. Read this file's FTI and element table if not previously read.

2. Return the file's next write location in A1.


3.2. PFS$ - Search for Element Entry
[Top][Contents]
        LA,U A0,PFPKT       . (2+6 input, 10 output)
        ER   PFS$

1. Read this file's FTI and element table if not previously read.

2. Search for the element entry.

3. If found, copy the entry to the packet and return the element's sequence number in A1.

The same ER rules for version searching and most recent executable apply.


3.3. PFI$ - Insert Element Entry
[Top][Contents]
        LA,U A0,PFPKT       . (2+10)
     [ LNA,U A0,PFPKT  ]
     [  LA   A1,NewLoc ]
        ER   PFI$

1. Read this file's FTI and element table if not previously read.

2. Insert the element entry into the file's element table.

3. If the second format is used, perform the functions of ER PFUWL$.

As with the ER, a zero date/time word in the element entry is filled with the current date/time.


3.4. PFD$ - Mark Element Entry Deleted
[Top][Contents]
        LA,U A0,PFPKT       . (2+6)
        ER   PFD$

1. Read this file's FTI and element table if not previously read.

2. Mark the element entry as deleted.

3. Write back the element table and FTI.


3.5. PFUWL$ - Update Next Write Location
[Top][Contents]
        LA,U A0,PFPKT       . (2)
        LA   A1,NewLoc
        ER   PFUWL$

1. Read this file's FTI and element table if not previously read.

2. Store the new next write location in the FTI.

3. Write back the element table and FTI. Will read the FTI and element table back on the next ER PFx$ for this file.


4. ERPFX$ Return Statuses
[Top][Contents]

Following an intercepted ER PFx$, ERPFX$ usually returns one of these standard ER PFx$ statuses in A2:

0 - Normal return.

1 - No-find.

2 - I/O error, or file not assigned.

3 - File not defined as program file.

7 - Sequence number greater than maximum allowed. The maximum is ordinarily 5000 for Standard Program Files and 26,146 for Large Program Files; but this number may be reduced for Standard Files by procedure and entry point tables in the file. Invoking the utility TOCED (level 12R1 or higher) against a file will display its current and maximum number of elements, as will a @PRT,T of the file using FURPUR 32R5 or higher.

Instead of the above, ERPFX$ may return one of two non-standard statuses:

040 - Other BSP$ error. The status registers A0-A2 returned by BSP$ will be stored at the externally defined tag ERPFX$BSPERR, with the Fieldata name of the BSP$ function that caused the error at ERPFX$BSPERR+3.

041 - Too many files. The caller tried to use ERPFX$ with more files than were provided for in the ERPFX$SETUP call.

In addition, if RFTI$$ was called successfully during this call to ERPFX$, the A1 value returned will be stored at the externally defined tag ERPFX$RFTIA1. This value may have one or more bits set indicating the following:

4 - File is a Large Program File (LPF)

0100 - File is a Large Element File (LEPF)

0104 - File is a Large LEPF

0200 - File was empty and initialized on this call.

If neither the 4 or the 0100 bits is set, the file is a Standard Program File. If the ERPFX$RFTIA1 tag is negative, no normal status from RFTII$ was stored during this ERPFX$ call, either because there was an error or because this particular type of call did not require it. An example of the latter is doing an ER PFI$ to a file that was previously initialized by an ER PFWL$ call.

However, on all subsequent ER PFx$ calls to this file, H2 of ERPFX$RFTIA1 will always contain the size indicator bits for the file (4 and/or 0100).


5. Non-Standard Calls
[Top][Contents]

Calls to ERPFx$ ERs are always preceded by a LA,U of A0 with the program file packet. The upper half of A0, normally 0, may be loaded with other bits to trigger other actions by BSP$.


5.1. File Initializing
[Top][Contents]

If a file being accessed by an ER PFx$ has not yet been initialized, these values may be loaded into the upper half of A0 to set bits for initializing it as other than a standard program file:

4 - Large Program File (LPF)

0100 - Large Element File (LEPF)

0104 - Large LEPF

Example:

        LA   A0,(0100,PFPKT)
        ER   PFWL$

If the file was already initialized, these bits will be ignored.


5.2. Reading/Writing the FTI & Elt Table
[Top][Contents]

As described above, the five intercepted PFx$ ERs have their own defaults regarding when to read a file's FTI and element table, and when to write them back. Values may be added to H1 of A0 to force or override these actions:

1 - Force read of file's FTI and element table. This might be desired if, for instance, the same internal filename is used for a different file from the one accessed by the previous ER PFx$.

2 - Force update of file after performing the action of this ER. One example of this might be to initialize a file and immediately write it out as initialized:

        LA   A0,(4+2,PFPKT) . Initialize file as LEPF
        ER   PFWL$

This bit will be ignored for an ER PFI$ without a LNA of A0 to signal updating the last write location; otherwise incorrect information would be written to the file.

020 - Override update of file. This might be used if several consecutive PFD$s are being performed. It would only be necessary to update the file on the last PFD$, or on a subsequent PFWL$ call with the "2" bit.

This bit will be ignored for an ER PFUWL$ or an ER PFI$ which updates the file's next write location.

Note that if any of these non-standard calls are used for an ER PFI$ call that updates the next write location, the entire word, including the extra bits, must be loaded negative, as in "LNA A0,(0101,PFPKT)".


5.3. Preventing ER PFx$ Interception
[Top][Contents]

If for some reason a program using ERPFX$ needs to use an actual PFx$ ER rather than having it intercepted, code a second subfield of 0:

ER PFS$,0


Table of Contents

(Go to Top)

1. Introduction
2. Implementation
3. Operation
3.1. PFWL$ - Obtain Next Write Location
3.2. PFS$ - Search for Element Entry
3.3. PFI$ - Insert Element Entry
3.4. PFD$ - Mark Element Entry Deleted
3.5. PFUWL$ - Update Next Write Location
4. ERPFX$ Return Statuses
5. Non-Standard Calls
5.1. File Initializing
5.2. Reading/Writing the FTI & Elt Table
5.3. Preventing ER PFx$ Interception