⎕FWRITE Append, replace or insert component

The ⎕FWRITE function allows you to write a component anywhere in the file, either inserting, replacing or appending. The syntax is:

      DATA ⎕FWRITE TIENO {COMPONENT} {PASS}

DATA is any APL array, or an overlay created using ⎕OV. TIENO is the tie number you used to tie or create the file (or the tie number returned by APLX if you tied or created it using 0 instead of your own tie number). If you tied the file using a pass number, you must provide the same pass number, as the PASS parameter.

COMPONENT is the component number at which the data should be written. This can be one of the following:

• If COMPONENT is zero, or is omitted, or is equal to the highest current component number plus 1, the data is written to the next available component number in the file (i.e. the highest current component number plus 1). If the file currently contains no components, the data will be written as component 1. This behavior is the same as that of ⎕FAPPEND.

  For example, if the file currently contains components 1 to 6, the following are all equivalent; the data will be written as a new component 7:

              DATA ⎕FWRITE TIENO
              DATA ⎕FWRITE TIENO,0
              DATA ⎕FWRITE TIENO,7
  

• If COMPONENT is an integer which corresponds to an existing component, the existing component is replaced by the new data supplied. For example, if the file currently contains components 1 to 6, and you supply a COMPONENT parameter of 3, the third component will be replaced by the new data you write. The number of components is unchanged. If the new array is bigger than the previous data, the necessary space will be allocated automatically. If the new array is smaller, the released space will be kept in a pool of available space and re-used if possible in a future operation. This behavior is the same as that of ⎕FREPLACE.

• If COMPONENT is a non-integral number between the first existing component minus 1, and the last component number plus 1, a new component is inserted and the data is written to the new component. The new component will be placed at the component number ⌈COMPONENT. Any later components will be renumbered to allow for the inserted component.

  For example, if the file currently contains components 1 to 6, the following statement would insert a new component between the existing fifth and sixth components, with the old sixth component becoming the new component 7:

              DATA ⎕FWRITE TIENO,5.5
  

  If the file currently contains components 3 to 8, then the following statement would insert a new component (as the new component 3) before the current first component. The existing components would be renumbered 4 to 9:

              DATA ⎕FWRITE TIENO,2.5
  

  If the number is between the current highest component number and the current highest component number plus 1, the operation is equivalent to appending a new component.

• Any other component number gives rise to an error COMPONENT NOT IN FILE (error code 20 in ⎕LER, or 6 3 in ⎕ET)

The following complete sequence illustrates the various possibilities:

Create a new file, and append four components to it in different ways:

      'EXAMPLE' ⎕FCREATE 
      'First component' ⎕FWRITE 2 1
      'Second component' ⎕FWRITE 2
      'Third component' ⎕FWRITE 2 0
      'Fourth component' ⎕FWRITE 2 3.5

Read back the four components:

      ⎕DISPLAY ⎕FREAD ¨2,¨⍳4
┌→──────────────────────────────────────────────────────────────────────────┐
│ ┌→──────────────┐ ┌→───────────────┐ ┌→──────────────┐ ┌→───────────────┐ │
│ │First component│ │Second component│ │Third component│ │Fourth component│ │
│ └───────────────┘ └────────────────┘ └───────────────┘ └────────────────┘ │
└∊──────────────────────────────────────────────────────────────────────────┘

Drop the first component, components are now number 2 to 4:

      ⎕FDROP 2 1
      ⎕FSIZE 2
2 5 3584 0 256
      ⎕FREAD 2 1
COMPONENT NOT IN FILE
      ⎕FREAD 2 1
      ^

Replace component 3 with a new value:

      'Third rewritten' ⎕FWRITE 2 3
      ⎕FREAD 2 3
Third rewritten

Insert a new component before the existing first component, renumbering existing components to allow for it:

      'Inserted first' ⎕FWRITE 2 1.5
      ⎕FREAD 2 2
Inserted first

Insert a new component between the existing third and fourth components (it will become the new component 4):

      'Interloper' ⎕FWRITE 2 3.5

See what we've ended up with:

      ⎕FSIZE 2
2 7 4096 0 0

(First component number is 2, next available is 7)

      ⎕FREAD 2 2
Inserted first
      ⎕FREAD 2 3
Second component
      ⎕FREAD 2 4
Interloper
      ⎕FREAD 2 5
Third rewritten
      ⎕FREAD 2 6
Fourth component

We're done. Untie the file:

      ⎕FUNTIE 2