Program Functions

Table 1 presents the conditions under which the open or EOV routines transfer control to your editor routines. Each condition suggests what your routine can do to permit processing of the current volume to continue. The first two conditions (density—type conflicts) arise only when the tape volume is mounted on a dual-density tape device.

General flowcharts of editor routines are shown in Figure 1 and Figure 2. The logic is shown separately for routines that receive control from the open or EOV routine of the control program. Each block in each of the flowcharts is numbered; each number corresponds to an item in the lists of explanations that follow the figures. Other points to note are:

The logic in the flowcharts is oriented toward resolving the label and density—type conflicts by altering the characteristics of the mounted volume.
Figure 2 (the EOV editor routine) does not contain logic blocks corresponding to blocks 5, 18, and 19 in Figure 1 (the open editor routine). These blocks represent functions that you must program only when receiving control from the open routine. You must test all the DCBs defined by the OPEN macro instruction before returning control to the open routine. When you receive control from the EOV routine, there is only one DCB to process.
If you do not support expiration date and protection checking on nonstandard label volumes, or maintain such checking on standard label volumes, you need not implement the functions of logic blocks 6 through 14 in the flowcharts.
The DCB is copied into protected storage during open, close, or EOV processing. During open processing, register 7 points to a parameter list that contains the addresses of the DCBs in protected storage. During EOV processing, register 2 points to the DCB in protected storage. The address of the user's DCB is in the open, close, EOV work area at the label DXUDCBAD. If the DCB is to be changed, both copies must receive the same change.

Table 1. Editor Routine Entry Conditions from the Open and EOV Routine
Program Specification	Mounted Volume Characteristics	Transfer Conditions	Possible Editor Routine Action
SL or AL	NSL or NL¹	Label—Type Conflict²	Write a standard volume label. (See Figure 1: blocks 15, 15A, and 16. If you support protection and retention date checking on NSL volumes, see block 6.)
NSL or NL	SL³ or AL⁴	Label—Type Conflict	Overwrite standard label with tapemark, for example, cancel. (See Figure 1: blocks 15, 15A, and 16.) Depending on whether NL or NSL is specified by the program, open or EOV either positions tape (NL) or transfers control to your nonstandard label routines (NSL).
AL	SL	Label—Type Conflict	Overwrite an IBM standard label with a Version 3 or Version 4 VOL1 label.
SL	AL⁴	Label—Type Conflict	Overwrite ISO/ANSI label with an IBM standard label.
AL or SL	AL⁴ or SL	Density Conflict	Overwrite the existing standard label with the requested standard label. The first write from load point sets the recording density on a dual-density device. (See Figure 1 or Figure 2: blocks 15B, 16, and explanation.)
NSL	NSL or NL with different density	Density Conflict	Write a tapemark to set density. The program specification NSL gives control to your nonstandard label routines after return to Open or EOV. (See Figure 1: blocks 15, 15B, and 16. If your installation supports protection and retention date checking on NSL volumes, see block 6.)
AL or SL	AL or SL	Volume Serial Conflict	Overwrite volume label with requested volume serial number.
AL	AL⁴	Version Coexistence Conflict	Overwrite an ASCII label with a Version 3 or Version 4 label (first file output only).
Compacted or non-compacted mode	Opposite of mode specified	Mode Conflict	No action taken.
Cartridge	36-track cartridge mounted on an 18-track drive	Track Conflict	Overwrite existing volume label so that it is compatible with drive.

Legend:
AL: ISO/ANSI standard volume label
SL: IBM standard volume label
NSL: Nonstandard volume label
NL: No volume label

Notes:

If the volume is mounted on a dual-density device, a density condition might also exist. The write operation corrects this.
When SL is specified, a label—type conflict might also indicate that the system could not recognize the first record because of a unit check condition.
If NL is specified, no density check is performed. For NL volumes, tape is positioned at load point and recording density is set by the first write command.
The open and EOV routines position the tape at load point before transferring control to the editor routines.

Figure 1. General Flow of an Editor Routine after Receiving Control from the Open Routine

Figure 2. General Flow of an Editor Routine after Receiving Control from the EOV Routine

Explanation of Logic Blocks-Figures Figure 1 and Figure 2

1

Your exception routine receives control from the open or EOV routines of the control program.

2

Use the GETMAIN macro instruction. The virtual storage you get must contain all your work areas, including those used to read in a label or write a label.

3

Use the store multiple (STM) instruction.

4

Figure 1 provides the information you need to establish addressability of the DCB address list and work and control block area for each DCB defined by the OPEN macro instruction.

When you receive control from the EOV routine, general register 2 contains the address of the DCB for the data set, and general register 4 contains the address of the work and control block area associated with the DCB.

The IECDSECT macro instruction (described in Mapping the Common Open, Close, EOV Work Area) symbolically defines the fields of the work and control block area (see Figure 2).

Also, address the UCB for the device on which the tape volume is mounted. You can get the address of the UCB from the DXDEBUCB field of the DEB defined by the IECDSECT macro instruction. The IEFUCBOB macro instruction defines the fields of the unit control block.

5

Bit configurations in the byte addressed by JFCBMASK+5 indicate whether label—type conflicts or density conflicts have occurred and, in the case of a label—type conflict, the condition that caused the conflict. Now test bits 0 and 3. If either bit is set to 1, processing is required. However, if bits 6 and 7 of DCBOFLGS are set to 0, you should discontinue processing. When bit 6 (lock bit) is 0, the control program cannot open the DCB. When bit 7 (busy bit) is 0, the DCB is already being processed or is already open.

The field JFCBMASK is defined by the IECDSECT macro instruction. Bit settings in the byte at JFCBMASK+5 are defined as:

Bits	Setting	Meaning
0	1	Label—type conflict has occurred.
1	1	Standard label (SL or AL) specified; no label/nonstandard label on mounted volume. If JFCBAL (AL label requested) is set and UCCBBSTR is set in the UCB (ASCII tape is mounted), an ISO/ANSI version conflict has occurred, and a valid Version 3 or Version 4 volume label must be created.
2	1	No label (NL) or nonstandard label (NSL) specified; standard label (AL or SL) on mounted volume.
3	1	Density conflict
4	1	Track conflict. The system has reconstructed a volume label from sense bytes.
5	1	See step 12
6-7		Reserved for future use

6

If your installation supports a protection and retention date scheme involving nonstandard labels, or if you want to maintain retention date and protection checking on standard labels, you must incorporate code in your editor routines to check for protection and retention date expiration.

To check, you must read the first record and determine the label type.

For I/O, move your CCWs into the channel program field of the work and control block area. (The symbolic name for the first entry in this field is DXCCW.) Then, issue an EXCP macro instruction specifying the address of the control program's IOB. (The symbolic name for the IOB is DXIOB.) These fields (DXCCW, DXIOB) are defined by the IECDSECT macro instruction. There are 12 CCW locations in the DXCCW field. There are 12 CCW locations in the DXCCW field. You can only use the first six locations.

7

To check the retention date or protection fields in a standard label, you must read the data set header 1 record into a work area. The format of the nonstandard label you define determines how you access those fields in the nonstandard label. Step 6 provides directions for handling the I/O operation.

8

Write a message to the operator stating that the volume is protected and asking if it is to be used.

9

Repeat step 7.

10

Write a message to the operator that the expiration date for the mounted volume has not elapsed and to determine if it is to be used.

11

If the volume is to be used, continue processing to resolve label or density conditions.

12

Rewind and unload the currently mounted volume. Step 6 provides directions for handling the I/O operation. When you issue the rewind and unload command, you must turn on the UCB not-ready bit (UCBFL2) after the ECB has been posted. If you want the open or EOV mount verification routines to handle the mounting or removing on volume verification, set bit 4 (X'08') of JFCBMASK+5 in the open or EOV work area and go to block 22 to return to open or EOV. Subsequent volume level errors cause the label editor routines to be reentered.

13

Write a message to the operator requesting removing of the current volume and mounting of a new volume. You can get the 4-digit device number (in binary) from the UCBCHAN field of the UCB. Step 6 provides directions for handling the I/O operation.

14

If a new volume is to be mounted, repeat step 6.

15

Test bit 3 of the byte at JFCBMASK+5. If set to 1, control was received as a result of a density conflict.

Test bit 0 of the byte at JFCBMASK+5. If set to 1, control was received as the result of a label—type conflict.

a: If control was received as the result of a label—type conflict, test bits 1 and 2 of the byte at JFCBMASK+5. See step 5.
b: If control is received as the result of a density conflict, use the JFCBLTYP field in the JFCB to determine the type of label in the program. A X'04' indicates a NSL has been specified; a X'02' indicates a standard label has been specified.

16

When you correct a density conflict or label—type conflict condition, and the program specifies an NSL, record the tape whether the open or EOV routines interpret as a nonstandard label or no label. For example, it does not contain VOL1 in the first four bytes of the record. The easiest way to do this is to write a tapemark. Upon return to open or EOV and reverification of the label, the specification for label type and density will have been met. If you've specified NSL, OPEN or EOV transfers control to your nonstandard label routines. If you've specified NSL, it positions the tape for writing.

You must supply information for the label identifier, the label number, and the volume serial number fields, and record the balance of the label as blanks.

Enter VOL in the label identifier field, a 1 in the label number field, and a 6-character serial number in the volume serial number field. To ensure that two or more tape volumes carrying the same serial number are not produced, write to the operator at this point for assignment of a serial number.

Data set header labels 1 and 2 are constructed by the open or EOV routine after control is returned to them.

Note: At this point, you can change the control block settings to conform to the characteristics of the tape volume mounted (that is, reset the label type field in the JFCB to conform with the type of label on the volume mounted and change the density field in the DCB to the density of the tape mounted).

17

The symbolic name for the volume serial number field in the UCB is UCBVOLI. The mount switch is the high-order bit of the field named UCBDMCT in the UCB. These fields are defined by the IEFUCBOB macro instruction. Perform an exclusive OR (XC) operation on the UCBVOLI field with itself and perform an OR (OI) operation on the UCBDMCT field with X'80'. This causes the mount verification routines to bypass further label processing and reverify the tape without an intervening removal.

18

When receiving control from the open routine, you must process the entire DCB list. The last entry in the list can be recognized by a 1 in bit 0 of the first byte in the entry.

19

You increase the pointer to the DCB address list by 4 bytes. You must also increase the pointer to the work and control block area for each DCB. You increase this pointer by 8 bytes.

20

Use the load multiple (LM) instruction.

21

Use the FREEMAIN macro instruction.

22

Return control to the open or EOV routine using the following code:

         MVC   0(L'IDRETURN,6),IDRETURN
         XCTL  EPLOC=(6),SF=(E,DXCCW12)
IDRETURN DC    CL8'nnnnnnnn'  Name of return routine

nnnnnnnn is the name of the routine to return to. In OMODVOL1 the name is IGG0190A. In EMODVOL1 the name is IGG0550P.

Return From: To Module
OMODVOL1: IGG0190A (Open)
EMODVOL1: IGG0550P (EOV)

Note: Open and EOV rewind the volume upon receiving control from OMODVOL1 or EMODVOL1.