Now that we can successfully read data it is time to look at writing. There are two types of write commands, Write Format and Write Update. The Write Update commands are used to update an existing block and include the Write Data and the Write Key and Data CCW commands. The Write Count, Key and Data command is a formatting command. It is used to add blocks to a track. Use of this command may also result in the removal of blocks from a track.
When a block is added to a track any previously existing blocks following the point where the new block is added will be deleted. For example if a track contained five blocks (block-1, block-2, block-3, block-4, block-5) and a Write CKD for block-3 is issued to the track the original blocks 3, 4, and 5 will be deleted and replaced with the new block-3. The updated track will then contain only three blocks (block-1, block-2, and block-3).
As the name implies the Write CKD command will write the Count, Key and Data components of a record. We must supple all three to the write command. The Count Area is eight bytes and consists of the record address in the format CCHHR (5 bytes), a key length (1 byte), and the data length (2 bytes). Immediately following the Count Area is the Key data (if the key length is non-zero). The length of the key data is specified in the Count Area. The record data follows the key data. As with the key the length of the data is specified in the Count Area. The total of the length of the Count, Key and Data is the length we specify as the CCW length.
Code To Write Data
It is important to remember that we are writing data and if not careful serious damage could be done by writing to the wrong dataset. To minimize the chance of accidently destroying something I changed the DDNAME in the DCB to EXCPWRIT. This serves as a reminder to me to not write over SYS1.LINKLIB or my source PDS.
Our initial program to write DASD blocks is EXCP06. Much of the code is the same as in our previous examples. Here we will just examine the code specific to this exercise.
OPEN (EXCPDCB,OUTPUT)
We have to specify OUTPUT on our OPEN macro. If we open the DCB in INPUT mode then write commands will be disabled in the Device Mask and all Write CCW Commands will fail.
DS 0D
CCWSRCH DC X'31',AL3(IOBSRCH),X'40',X'00',AL2(5)
CCWTIC DC X'08',AL3(CCWSRCH),X'40',X'00',AL2(0)
CCWWRITE DC X'1D',AL3(CARDBUF1),X'40',X'00',AL2(88)
DC X'1D',AL3(CARDBUF2),X'40',X'00',AL2(88)
DC X'1D',AL3(CARDBUF3),X'40',X'00',AL2(88)
DC X'1D',AL3(CARDBUF4),X'40',X'00',AL2(88)
DC X'1D',AL3(CARDBUF5),X'00',X'00',AL2(88)
Here is our Channel Program we will use to write blocks. It is similar to our read Channel Programs. It begins with a Search ID Equal (for Record Zero) followed by a TIC. When then have a series of Write CKD CCWs to write 5 records. We are writing 80 byte records so our data length is 88 (80 bytes of Data + 8 bytes for the Count). These are non-keyed records (key length = 0). Note the Command Chain bit is set for all but the last write command.
* C C H H R KL DL CARDBUF1 DC X'00000000',X'01',AL1(0),AL2(80),CL80'CARD1' CARDBUF2 DC X'00000000',X'02',AL1(0),AL2(80),CL80'CARD2' CARDBUF3 DC X'00000000',X'03',AL1(0),AL2(80),CL80'CARD3' CARDBUF4 DC X'00000000',X'04',AL1(0),AL2(80),CL80'CARD4' CARDBUF5 DC X'00000000',X'05',AL1(0),AL2(80),CL80'CARD5'
Here are the five data buffers for the records we will be writing. Each consists of 8 bytes for the Count and 80 bytes of data. For now the CCHH is set to zeros. When we calculate the actual Cylinder-Head address using the DEB extent data we will fill in these fields. Next is the record number followed by the key length and data length values. Finally we have the 80 bytes of data.
*
***********************************************************************
* WRITE 5 BLOCKS TO TRACK 0 WITH ONE I/O
***********************************************************************
*
LA R1,0 RELATIVE TRACK NUMBER ZERO
BAL R14,GETCCHH CONVERT TO MBBCCHHR
LTR R15,R15 CHECK RETURN CODE
BZ WRITE010 - BRANCH IF GOOD
*
WRITE000 DS 0H
LOG 'TTR CONVERSION FAILED'
WTO 'TTR CONVERSION FAILED',ROUTCDE=(1,11)
B EXIT
We begin by calculating the actual Cylinder-Head address for relative track zero.
WRITE010 DS 0H
MVC IOBSEEK(8),MBBCCHHR
MVC CARDBUF1(4),MBBCCHHR+3
MVC CARDBUF2(4),MBBCCHHR+3
MVC CARDBUF3(4),MBBCCHHR+3
MVC CARDBUF4(4),MBBCCHHR+3
MVC CARDBUF5(4),MBBCCHHR+3
We can then set the CCHH address into the IOB Seek field as well as in the Count Area of our I/O buffers.
MVI IOBSEEK+7,0 SEARCH FOR R0
*
XC ECB,ECB CLEAR ECB
EXCP IOB ISSUE I/O REQUEST
*
WAIT 1,ECB=ECB WAIT FOR I/O TO COMPLETE
*
LA R14,EXIT
CLI IOBECBAD,X'7F' WAS IT SUCCESSFUL
BNE PRINTIOB GO FORMAT IOB AND EXIT
Since we want to write record number one we have to search for Record Zero. If the track is properly formatted it will always have a Record Zero which is not considered to be a data record. We can then issue the EXCP and wait for it to complete. If the EXCP request was not successful we print out the IOB status fields and exit.
***********************************************************************
* WRITE 5 BLOCKS TO TRACK 1 ONE I/O
* REWRITE BLOCK 1 (WRITE CKD)
***********************************************************************
*
LA R1,1 RELATIVE TRACK NUMBER ZERO
BAL R14,GETCCHH CONVERT TO MBBCCHHR
LTR R15,R15 CHECK RETURN CODE
BNZ WRITE000 - BRANCH IF FAIL
*
MVC IOBSEEK(8),MBBCCHHR
MVC CARDBUF1(4),MBBCCHHR+3
MVC CARDBUF2(4),MBBCCHHR+3
MVC CARDBUF3(4),MBBCCHHR+3
MVC CARDBUF4(4),MBBCCHHR+3
MVC CARDBUF5(4),MBBCCHHR+3
*
MVI IOBSEEK+7,0 SEARCH FOR R0
*
XC ECB,ECB CLEAR ECB
EXCP IOB ISSUE I/O REQUEST
*
WAIT 1,ECB=ECB WAIT FOR I/O TO COMPLETE
*
LA R14,EXIT
CLI IOBECBAD,X'7F' WAS IT SUCCESSFUL
BNE PRINTIOB GO FORMAT IOB AND EXIT
We will now do the same thing for relative track 1 and write the same five records.
*
MVI CCWWRITE+4,0 CLEAR COMMAND CHAIN BIT
XC ECB,ECB CLEAR ECB
EXCP IOB ISSUE I/O REQUEST
*
WAIT 1,ECB=ECB WAIT FOR I/O TO COMPLETE
*
LA R14,EXIT
CLI IOBECBAD,X'7F' WAS IT SUCCESSFUL
BNE PRINTIOB GO FORMAT IOB AND EXIT
Now we will write just one record to the same track. The Command Chain bit in the first Write CCW is cleared which will make it the last CCW in the Channel Program. This should result in only one record on the track since all previously existing records following the record being written are erased.
*
LA R1,2 RELATIVE TRACK NUMBER ONE
BAL R14,GETCCHH CONVERT TO MBBCCHHR
LTR R15,R15 CHECK RETURN CODE
BNZ WRITE000 - BRANCH IF FAIL
*
MVI CCWWRITE+4,0 CLEAR COMMAND CHAIN
*
MVC IOBSEEK(8),MBBCCHHR
MVC CARDBUF1(4),MBBCCHHR+3
MVC CARDBUF2(4),MBBCCHHR+3
MVC CARDBUF3(4),MBBCCHHR+3
MVC CARDBUF4(4),MBBCCHHR+3
MVC CARDBUF5(4),MBBCCHHR+3
Now we will write five records to relative track 2 but we will write them one at a time. We begin as before by calculating the CCHH address and updating the IOB Seek and Count fields in the I/O buffers.
*
MVI IOBSEEK+7,0 SERCH FOR R0
LA R1,CARDBUF1 RECORD 1
STCM R1,B'0111',CCWWRITE+1 UPDATE RECORD
*
XC ECB,ECB CLEAR ECB
EXCP IOB ISSUE I/O REQUEST
*
WAIT 1,ECB=ECB WAIT FOR I/O TO COMPLETE
*
LA R14,EXIT
CLI IOBECBAD,X'7F' WAS IT SUCCESSFUL
BNE PRINTIOB GO FORMAT IOB AND EXIT
Now we search for record zero. We place the I/O buffer for record one in the Write CKD CCW.
*
MVI IOBSEEK+7,1 SERCH FOR R1
LA R1,CARDBUF2 RECORD 2
STCM R1,B'0111',CCWWRITE+1 UPDATE RECORD
*
XC ECB,ECB CLEAR ECB
EXCP IOB ISSUE I/O REQUEST
*
WAIT 1,ECB=ECB WAIT FOR I/O TO COMPLETE
*
LA R14,EXIT
CLI IOBECBAD,X'7F' WAS IT SUCCESSFUL
BNE PRINTIOB GO FORMAT IOB AND EXIT
To write the second record we update the search address to record one (the record we just wrote). We also place the I/O buffer for record two into the Write CKD CCW.
*
MVI IOBSEEK+7,4 SERCH FOR R4
LA R1,CARDBUF5 RECORD 5
STCM R1,B'0111',CCWWRITE+1 UPDATE RECORD
*
XC ECB,ECB CLEAR ECB
EXCP IOB ISSUE I/O REQUEST
*
WAIT 1,ECB=ECB WAIT FOR I/O TO COMPLETE
*
LA R14,EXIT
CLI IOBECBAD,X'7F' WAS IT SUCCESSFUL
BNE PRINTIOB GO FORMAT IOB AND EXIT
The code to write records 3, 4, and 5 is same – each time updating the serarch field and the I/O buffer address.
At this time we should have written three tracks to our dataset. The first track contains 5 blocks, the second contains 1 blocks, and the third contains 5 blocks. Now we need an EOF record. Instead of writing the EOF ourselves we will allow EXCP to do it for us during CLOSE processing. This will also update the last track used and track balance fields is the DSCB. We need to supply the address of the last block we have written as well as the space remaining (track balance) for the last track used. We do this by placing these values into the DCB prior to issuing the CLOSE macro.
MVC EXCPDCB+5(8),IOBSEEK LAST MBBCCHHR USED
MVC EXCPDCB+8(5),CARDBUF5
*
L R1,=A(19254) EMPTY TRACK BALANCE
S R1,=A(185+80) R1
S R1,=A(185+80) R2
S R1,=A(185+80) R3
S R1,=A(185+80) R4
S R1,=A(185+80) R5
STCM R1,B'0011',EXCPDCB+18 TRACK BALANCE
We need the MBBCCHHR of the last record. The MBB portion is contained in the IOBSEEK field. We then copy the CCHHR from the Count Area of our last I/O buffer (the last block written).
Now we have to calculate the track balance. We begin with the empty track valance value (19,254 for a 3350) and subtract out the values for the blocks written. A non-keyed record has an overhead of 185 bytes (which includes the Count Area length). We add this to the data length to get the number of bytes consumed by a record and subtract it from the track balance. This value is stored into the DCB. I am using fixed offset values into the DCB. These fields are mapped by the DCBD macro so you could choose to use symbolic names.
As part of this exercise I was looking for how to get these values from the DSCB when opening a dataset. I had expected to find them in the JFCB but they were now where to be found. It is possible they are available if various options are specifed (such as DISP=MOD) or Open for Update. Instead of trying various combinations to cause Open to provide the values I used RDJFCB to read get the JFCB for the open dataset. From the JFCB I can get the Dataset Name and the Volume Serial. With this information I can read the Format 1 DSCB using the OBTAIN macro. This then gives me access to the last track used and track balance values stored in the DSCB. Although these values are not used in this example I do include the code to obtain them.
Upon running the program we should have a dataset containing 11 records. I used TSO EDIT to view the contents of the dataset.
edit 'tcs3.excp06.data' cntl DATA SET 'TCS3.EXCP06.DATA' NOT LINE NUMBERED, USING NONUM EDIT list CARD1 CARD2 CARD3 CARD4 CARD5 CARD1 CARD1 CARD2 CARD3 CARD4 CARD5 END OF DATA end nos READY
The results are exactly as expected. I was interested in peeking a little deeper into the contents of the tracks in the dataset. I created a utility program that will report on the blocks making up the tracks in a dataset. The source for this program (DSUINFO) is available in the downloads. I use the Read Multiple CKD CCW Command to read the tracks and then report some basic information for each track.
Here is the DSUINFO output for the dataset created by EXCP06.
---------- DSUINFO ----------
TCS3.EXCP06.DATA VOL=SER=WORK01 DEV TYPE=3350
EXTENTS = 1 TRACKS = 3 BLKSIZE = 80 LRECL = 80 DSORG = PS RECFM = F
TT= 0 CC=0148 HH=000F BLKS= 5 EOF= 0 KL= 0/ 0/ 0 DL= 80/ 80/ 80
TT= 1 CC=0148 HH=0010 BLKS= 1 EOF= 0 KL= 0/ 0/ 0 DL= 80/ 80/ 80
TT= 2 CC=0148 HH=0011 BLKS= 5 EOF= 0 KL= 0/ 0/ 0 DL= 80/ 80/ 80
TT= 3 CC=0148 HH=0012 BLKS= 0 EOF= 1 KL= 0/ 0/ 0 DL= 0/ 0/ 0
TT= 4 CC=0148 HH=0013 BLKS= 0 EOF= 1 KL= 0/ 0/ 0 DL= 0/ 0/ 0
We can see there are 5 tracks in the dataset. It was allocated with SPACE=(TRK,(5,0)). The first track contains 5 data blocks and no EOF blocks. The Min/Max/Avg Key Lenght is 0 and the Min/Max/Avg Data length is 80. The second track contains one block and the third track contains 5 blocks. You may notice the EOF occurs on the fourth track. The last track simply contains whatever was left over from previous use. In this case it happens to be a single EOF block.
Now an interesting question might be what happens if the dataset is alloced with only three tracks – where will the EOF be located?
---------- DSUINFO ----------
TCS3.EXCP06.DATA VOL=SER=WORK01 DEV TYPE=3350
EXTENTS = 1 TRACKS = 3 BLKSIZE = 80 LRECL = 80 DSORG = PS RECFM = F
TT= 0 CC=006A HH=001B BLKS= 5 EOF= 0 KL= 0/ 0/ 0 DL= 80/ 80/ 80
TT= 1 CC=006A HH=001C BLKS= 1 EOF= 0 KL= 0/ 0/ 0 DL= 80/ 80/ 80
TT= 2 CC=006A HH=001D BLKS= 5 EOF= 0 KL= 0/ 0/ 0 DL= 80/ 80/ 80
And here is the answer to that question. There is no EOF record written. If all tracks in all extents are read without ever encountering an EOF record then the EOF is implied to exist after the last record in the last extent.
Finally we can check the DSCB to verify the last track used and the track balance are valid.
Last Block Used TTR ... 000205 Bytes Unused Last Trk . 4609 (17929)