Page of GC20-1819-2 As Updated April 27, 1981 by TNL SN25-0828 For 5748-XE1 The fileid must be specified either in the FSCB for a file or FSREAD, FSWRITE, FSOPEN, or FSERASE macro instruction you use references the file. on the that FSCBITNO: For an FSCB without the FORM=E option, the record or item number-indicates the relative record number of the next record to be read or written; it can be changed with the RECNO option. The default value for this field is o. When you are reading files, a 0 indicates that records are to be read sequentially, beginning with the first record in the file. When you are writing files, a 0 indicates that records are to be written sequentially, beginning at the first record following the end of the file, if the file already exists, or with record 1, if it is a new file. For an FSCB generated with the contains the record or item number. FORM=E option, the FSCBAITN field The FSCBITNO field is reserved. Whenever you read discontiguous files in CMS (that is, files with missing records), the input buffer will be filled with the appropriate number of bytes. Be aware that the flag byte in the FSCB may not reflect whether the input buffer contains generated data items from RDBUF. FSCBBQff: The buffer address, specified in the BUFFER option, indicates the label of the buffer from which the record is to be written or into which the record is to be read. You should always supply a buffer large enough to accommodate the longest record you expect to read or write. This field must be specified, either in the FSCB, or on the FSREAD or FSWRITE macro instruction. FSCBSIZE: This field indicates the number or nytes are read or written-with each read or write operation. The default value is O. If the buffer that you use represents the full length of the records you are going to be reading or writing, you can use the BSIZE option to set this field equal to your buffer length; when you are writing variable-length records, use the BSIZE operand to indicate the length of each record you write. This field must be specified. FSCB1Y: This field indicates the record format (RECFM) of the file. The default value is F (fixed). FSCBFLG: The flag byte is X'20' indicating an extended FSCB generated when-the FOBM=E option is coded on the FSCB macro instruction. FSCBNQ!T: For an FSCB without the FORM=E option, this field contains the number of whole records that are to be read or written in each read or write operation. For fixed-length records, you can use the NOREC option with the BSIZE option to block and deblock records. For variable-length records, the NOREC parameter must be 1. The default for the FSCBNOIT field is 1. For an FSCB generated with the FORM=E option, the FSCBANIT contains the number of whole records to be read or written. FSCBNOIT field is reserved. field The Following a read operation, this field contains the number of bytes that were actually read, so that if you are reading a variable-length file, you can determine the size of the last record read. The FSREAD macro instruction places the information from this field into register o. FSCBAITN: The alternate record or item number indicates the relative record-number of the next record to be read or written in an extended FSCB format. See the description of the FSCBITNO field for the usage of this field. section 13. programming for the CMS Environment 245
Page of GC20-1819-2 As Updated April 27, 1981 by TNL SN25-0828 For 5748-XE1 The fileid must be specified either in the FSCB for a file or FSREAD, FSWRITE, FSOPEN, or FSERASE macro instruction you use references the file. on the that FSCBITNO: For an FSCB without the FORM=E option, the record or item number-indicates the relative record number of the next record to be read or written; it can be changed with the RECNO option. The default value for this field is o. When you are reading files, a 0 indicates that records are to be read sequentially, beginning with the first record in the file. When you are writing files, a 0 indicates that records are to be written sequentially, beginning at the first record following the end of the file, if the file already exists, or with record 1, if it is a new file. For an FSCB generated with the contains the record or item number. FORM=E option, the FSCBAITN field The FSCBITNO field is reserved. Whenever you read discontiguous files in CMS (that is, files with missing records), the input buffer will be filled with the appropriate number of bytes. Be aware that the flag byte in the FSCB may not reflect whether the input buffer contains generated data items from RDBUF. FSCBBQff: The buffer address, specified in the BUFFER option, indicates the label of the buffer from which the record is to be written or into which the record is to be read. You should always supply a buffer large enough to accommodate the longest record you expect to read or write. This field must be specified, either in the FSCB, or on the FSREAD or FSWRITE macro instruction. FSCBSIZE: This field indicates the number or nytes are read or written-with each read or write operation. The default value is O. If the buffer that you use represents the full length of the records you are going to be reading or writing, you can use the BSIZE option to set this field equal to your buffer length; when you are writing variable-length records, use the BSIZE operand to indicate the length of each record you write. This field must be specified. FSCB1Y: This field indicates the record format (RECFM) of the file. The default value is F (fixed). FSCBFLG: The flag byte is X'20' indicating an extended FSCB generated when-the FOBM=E option is coded on the FSCB macro instruction. FSCBNQ!T: For an FSCB without the FORM=E option, this field contains the number of whole records that are to be read or written in each read or write operation. For fixed-length records, you can use the NOREC option with the BSIZE option to block and deblock records. For variable-length records, the NOREC parameter must be 1. The default for the FSCBNOIT field is 1. For an FSCB generated with the FORM=E option, the FSCBANIT contains the number of whole records to be read or written. FSCBNOIT field is reserved. field The Following a read operation, this field contains the number of bytes that were actually read, so that if you are reading a variable-length file, you can determine the size of the last record read. The FSREAD macro instruction places the information from this field into register o. FSCBAITN: The alternate record or item number indicates the relative record-number of the next record to be read or written in an extended FSCB format. See the description of the FSCBITNO field for the usage of this field. section 13. programming for the CMS Environment 245
Page of GC20-1819-2 As Updated April 27, 1981 by TNt SN2S-0828 For S748-XEl FSCBAB!!: This field contains the alternate number of whole records in an extended FSCB format. See the description of the FSCBNOIT field for the usage of this field. FSCBwglg: The FSPOINT macro instruction uses this field to contain the alternate write pointer for an extended FSCB during a POINT operation. The FSPOINT macro instruction uses this field to contain the alternate read pointer for an extended FSCB during a POINT operation. The following example shows how you might code an FSCB macro instruction to define various file and buffer characteristics, and then use the same FSCB to refer to different files: COMMON SHARE FSREAD 'INPUT FILE A1',FSCB=COMMON,FORM=E FSWRITE 'OUTPUT FILE Al',FSCB=COMMON,FORM=E FSCB BUFFER=SHARE,RECFM=V,BSIZE=200,FORM=E DS CL200 In the above example, the fileid specifications on the FSREAD and FSWRITE macro instructions modify the FSCB at the label COMMON each time a read or write operation is performed. You can also modify an FSCB directly by referring to fields by a displacement off the beginning of the FSCB; for example: HVC FSCB+8,=CL8'NEWNAME' moves the name NEWNAME into the filename field of the FSCB at the label FSCBFN. As an alternative, you can use the FSCBD macro instruction to qenerate a DSECT and refer to the labels in the DSECT to modify the FSCB; for example: INFSCB NEWNAME LA RS,INFSCB USING FSCBD,RS MVC FSCBFN,NEWNAME FSCB DC FSCBD 'INPUT TEST A1',FORM=E Ct8'OUTPUT' In the above example, the HVC instruction places the filename OUTPUT into the FSCBFN (filename) field of the FSCB. The next time this FSCB is referenced, the file OUTPUT TEST is the file that is manipulated. CMS disk files are sequential files; when you use CMS macros to read and write these files, you can access them sequentially with the FSREAD and FSWRITE macros. However, you may also refer to records in a CMS file by 246 IBM VM/370 eMS User's Guide
Page of GC20-1819-2 As Updated April 27, 1981 by TNL SN25-0828 For 5748-XE1 their relative record numbers, so you can, in effect, access records using a direct access method. If you know which record you want to read or write, you can specify the RECNO option on the FSCB macro instruction, or on the FSOPEN, FSREAD, or FSWRITE macro instructions. When you use the RECNO option on the FSCB macro instruction, you must specify it as a self-defining term; for the FSOPEN, FSREAD, or FSWRITE macro instructions, you may specify either a self-defining term, as: WRITE FSWRITE FSCB=WFSCB,RECNO=10,FORM=E or using register notation, as follows: WRITE FSWRITE FSCB=WFSCB,RECNO=(5) ,FORM=E where register 5 contains the record number of the record to be read. When you want to access files sequentially, the FSCBITNO field of the FSCB must be 0 for an FSCB without the FORM=E option; for an extended FSCB, the FSCBAITN field must be Oe This is the default value. When you are reading files with the FSREAD macro instruction, reading begins with record number 1. When you are writinq records to an existing file with To begin reading or writing files sequentially beginning at a specific record number, you must specify the RECNO option twice: once to specify the relative record number at which you want to begin reading, and a second time to specify RECNO=O so that reading or writing will continue sequentially beginning after the record just read or written. the FSWRITE macro, writing begins following the last record in the file. section 13. Programming for the CMS Environment 246.1
April 27, 1981 normally located on the system disk. To allow for proper macro expansion in a system supporting VM/370 System Extensions (Program No. 5748-XE1), CMSBSE MACLIB must be used in addition to CMSLIB 8ACLIB. There are macros to manipulate CMS disk files, to handle terminal communications, to manipulate unit record and tape input/output, and to trap interruptions. These macros are discussed in general terms here; for complete format descriptions, see VM/370 CMS gnd MACROS FOR DISK FILE MANIPULATION Disk files are described in CMS by means of a file system control block (FSCB). The macro instructions that manipulate disk files use FSCBs to identify and describe the files. When you want to manipulate a CMS file, you can refer to the file either by its file identifier, specifying 'filename filetype filemode' in quotation marks, or you can refer to the FSCB for the file, specifying FSCB=fscb, where fscb is the label on an FSCB macro. To establish an FSCB for a file, you can use the FSCB macro instruction specifying a file identifier; for example: INFILE FSCB 'INPUT TEST A1' You can also provide, on the FSCB macro instruction, descriptive information to be used by the input and output macros. If you do not code an FSCB macro instruction for a file, an FSCB is created inline (following the macro instruction) when you code an FSREAD, FSWRITE, or FSOPEN macro instruction. The format of an FSCB is listed below, followed by a description of each of t he fields. LaQ§1 FSCBCOMM FSCBFN FSCBFT FSCBFM FSCBITNO FSCBBUFF FSCBSIZE FSCBFV FSCBFLG FSCBNOIT FSCBNORD FSCBAITN FSCBANIT FSCBWPTR FSCBRPTR DC DC DC DC DC DC DC DC EQU DC DC DC DC DC DC CL8' , CL8' , CL8' , CL2' , H'O' A'O' F'O' CL2'F' FSCBFV+1 H' 1 ' AL4 (0) AL4 (0) AL4 (1) AL4 (0) AL4 (0) De,§cri:Q1io,!! File system command Filename F iletype Filemode Relative record number (RECNO) Address of buffer (BUFFER) Number of bytes to read or write (BSIZE) Record format -F or V (RECFf'!) Flag byte Number of records tc read or write (NOREC) Number of bytes actually read Extended FSCB relative record number Extended FSCB relative number of records Extended FSCB relative write pointer Extended FSCB relative read pointer The fields FSCBAITN, FSCBANIT, FSCBWPTR, and FSCBRPTR are only generated in the FSCB when the extended format FSCB is requested (FORM=E is coded on the FSCB macro instruction). In this case, the fields FSCBITNO and FSCBNOIT are reserved fields. Extended format FSCBs must be used to manipulate files larger than 65,533 items. The labels shown above are not generated by the FSCB macro; to reference fields within the FSCB by these labels, you must use the FSCBD macro instruction to qenerate a DSECT. 244 IBM VM/370 CMS User's Guide
April 27, 1981 When the FSCBFN, FSCBFT, and FSCBFM fields are filled in, you can fill in the FSCBCOMM field with the name of a CMS command and use the FSCB as a parameter list for an SVC 202 instruction. (You must place a delimiter to mark the end of the command line.) The filename, filetype and filemode fields identify the CMS file to be read or written. You can code the fileid on a macro line in the format 'filename filetype filemode' or you can use register notation. If you use register notation, the register that you specify must point to an 18-byte field in the format: FILEID DC DC De eL8'filename' CL8'filetype' CL2'fm' section 13. Programming for the eMS Environment 244.1