Chapter 3.2. File Control (DFHFC Macro Instruction)
86 CICS/VS APR!! (ML)
1\ 1\ 1\ 1\
1 I I I
BLOCK LOG LOG LOG
RDF REC REC REC
RDF RDF RDF
Figure 3.2-9. Record Identification Field (Addition of More than One' Record)
If only a single logical record is to be added, the block RDF is still required, as shown in Figure 3.2-10.
1 1 1 1 I
FWAIPREFIXI10811041<---100--->1
1 1 1 1 I
L I
1\ 1\
1 I BLOCK LOG
REC RDF RDF
Figure 3.2-10. Record Identification Field ~ddition of Single Record)
When updating records on a DAM dataset, the following restriction applies:
I
I
If the file is blocked, and if two or more records are to be updated, a DFHFC TYPE=GET macro to retrieve a record must be
followed by a DFHFC TYPE=POT macro to write the updated record (or a DFHFC TYPE=RELEASE macro if the updated record is not required) before any further record in the same block is retrieved for
update. Failure to do so will result either in one or more updates being lost or in a lockout.
86 CICS/VS APR!! (ML)
Direct Retrieval (TYPE=GET)
The format of the DFHFC macro instruction to retrieve single records directly from a data set is as follows:
DFHFC TYPE=GET
[ ,DATASET=symbolic name]
[,RDIDADR=symbolic address]
[ ,SEGSET={symbolic nameIYESIALL} ] [,INDEX={symbolic nameIYES}) [,TYPOPER=UPDATE]
[,RETMETH={RELRECIKEY}] <---DAM
[,ARGTYP={KEYIRBA}] < VSAM
[,SRCHTYP={FKEQIFKGEIGKEQIGKGE}] < VSAM [ , MODE= {MOVE I LOCATE} ] < VSAM [,DUPKEY=symbolic address] <---VSAM & assembler [,NORESP=symbolic address]
[,ERROR=symbolic address]
[ ,DSIDER=symbolic address]
[ ,SEGIDER=symbolic address]
[ ,NOTFND=symbolic address]
[,INVREQ=symbolic address]
[ , IOERROR=symbolic address]
[,DUPDS=symbolic address]
[,NOTOPEN=symbolic address]
[,ILLOGIC=symbolic address] <---VSAM
This macro instruction is used for direct read-only (inquiry) or update (DFHFC TYPE=GET, TYPOPER=UPDATE) operations. The requested record is returned in:
• a file input/output area (FIOA) for read-only operations with unsegmented, unblocked records from a DAM or ISAM data set or VSAM data set in move mode
• a file work area (FWA) for update operations, read-only operations with segmented or blocked records, or for read-only operations with a blocked VSAM data set
• in a VSAM buffer area for locate mode read-only operations on unsegmented records of a VSAM data set
Before this macro is used, instructions must be provided that define symbolically the required FIOA, FWA and/or VSWA by:
1. copying the appropriate storage definitions (DFHFIOA, DFHFWADS, and/or DFHVSWA) provided oy CICS/VS
2. providing storage definitions for the user's part of the FIOA, FWA, and/or the user's record in the VSAM buffer
Hote: Under CICS/OS/VS, if ISAM data is to be read into in an FIOA, a 16-byte filler must be defined following the statement that copies DFHFIOA and preceding the user's data definition.
CICS/VS performs the following services in response to a DFHFC TYPE=GET macro instruction:
1. Acquires the main storage areas required to read a record
Chapter 3.2. File Control (DFHFC Macro Instruction) 87
2. Reads the requested record
3. Makes the requested record available to the application program.
The record required in an input/output operation is identified in a record identification field. The format of this field, as required for the various access methods, is described under "Record Identification Pield", earlier in this chapter.
When a DAM data set is referenced, the record identification field should contain a block reference. When an ISAM data set is referenced, the record identification field should contain a key. When a VSAM data set is referenced, the required record is accessed by either a relative byte address or a key. A search by key may be for a key equal to the search key, or for one equal to or greater than the search key, or for one equal to or less than the search key. A search may also be for a partial key (the first two bytes, or any number specified by the
programmer), which may serve as a generic key. The generic or partial key search may, again, be either for an equal key or for an equal or greater key, or for an equal or less than key, but only the number of bytes specified will be compared. A protected, key-sequenced VSAM data set can be updated only by a full key equal search.
In addition, CICS/VS can perform the following services, depending on the operands included in this macro instruction:
• Retrieve a record indirectly
• segment a record for inquiry (read-only) and return the requested segments in a work area
• Acquire a file work area when the record is to be updated, or when records are blocked or segmented
• Unpack a segmented record into a work area of the same length as the requested record
The length of an acquired FWA depends on whether or not the record is to be updated. If the record is to be updated, the PWA acquired will be sufficient to contain a record of the maximum length specified by the system programmer in the PCT; otherwise, the PWA will be sufficient to contain the requested record.
When an unsegmented record of a VSAM data set is retrieved in
response to a read-only request, move mode or locate mode processing can be specified. In move mode, the record is handled in the same way as any DAM or ISAM record. In locate mode, the record is made available to the application program in the VSAM buffer. The application programmer must have copied the symbolic storage definition for the VSWA (DPHVSWA) and must also provide a symbolic storage definition for the record that is retrieved.
After requesting file services, the programmer must establish addressability for any required PIOA or PWA. The address of the area involved, provided by CICS/VS at TCAPCAA, must be placed in PIOABAR or PWACBAR. In locate mode, the address of the VSWA is in TCAPCAA and must be placed in VSWABAR. The address of the area that holds the requested record is at VSWAREA within the VSWA and must be moved to the base
locator that has been established for the symbolic storage definition of the area.
When retrieving variable-length records from a VSAM data set in move mode, the file control program creates a length field and places it preceding the record in the PiA. The format of this length field is
LL~, where LL is a two-byte binary length (including the q bytes for 88 CICS/VS APRM(ML)
the length field itself) and ~~ is two bytes of binary zeros. In locate mode, the length is not included in the record itself but is placed at VSWALEN in the VSWA.
When a VSAM record is retrieved for update,VSAM maintains exclusive control of the control interval containing that record. A task should not attempt to retrieve (for update) a second record from the same
control interval as a record it is already holding for update, otherwise a permanent wait will occur. The update should first be completed, by a DFHPC TYPE=PUT macro, or if i t cannot be completed, terminated by a DPHPC TYPE=RELEASE macro.
A DFHFC TYPE=RELEASE macro instruction frees an FIOA or FWA acquired in response to a request for file services, or a VSWA and VSAM string established for a VSA! read-only request using locate mode I/O. Any of these areas that are not freed by the application program are freed by CICS/VS at task termination.
Direct Retrieval @ead-only)
The following examples show how to retrieve a single record directly from a master data set, assuming blocked records.
For Assembler language:
COpy KEYF DS FWACBAR EQU
COpy RECORD DS
DFHTCADS CL8 1
DFHPWADS OCL350
MVC KEYF,ACCTNO READREC DFHFC TYPE=GET,
DATASET=MASTERA, RDIDADR=KEYF L FWACBAR,TCAPCAA
COpy TCA SYMBOLIC STRG DEPN RECORD IDENT PIELD IN TWA ASSIGN BASE REGISTER FOR PWA SYMBOLICALLY DEFINE FWA
RECORD LAYOUT FOLLOWS CONTROL FIELD AND HAS SAME BASE REGISTER
MOVE RECORD IDENT TO KEY FIELD GET RECORD FROM MASTER DATA SET
ESTABLISH ADDRESSABILITY FOR FWA
* *
Chapter 3.2. File Control (DFHFC Macro Instruction) 89
For COBOL:
02 FWACBAR PIC S9(8) CO!P.
01 DFHTCADS COPY DFHTCADS.
02 KEYF PIC X(8).
01 DFHFWADS COPY DFHFWADS.
02 RECORD PIC X(350).
PROCEDURE DIVISION.
MOVE CSACDTA TO TCACBAR.
MOVE ACCTNO TO KEYF.
READREC.
DFHFC TYPE=GET,
DATA SET=MAS TERA, RDIDADR=KEYF MOVE TCAFCAA TO FWACBAR.
For PL/I:
~INCLUDE DFHTCADS;
02 KEYF CHAR (8) ;
~INCLUDE DFHFWADS;
02 RECORD CHAR (350) ;
KEYF=ACCTNO;
READREC:
DFHFC TYPE=GET,
DATASET=MASTERA, RDIDADR=KEYF FWACBAR=TCAFCAA;
90 CICS/V 5 APRM (~L)
NOTE DEFINE BASE REGISTER FOR FWA.
NOTE COpy SYMBOLIC STRG DEFN FOR TCA.
NOTE DEFINE KEY FIELD IN TWA.
NOTE COpy SYMBOLIC STRG DEFN FOR FWA.
NOTE DEFINE RECORD LAYOUT IN FiA.
NOTE ESTABLISH TCA ADDRESSABILITY.
NOTE MOVE RECORD IDENT TO KEY.
GET RECORD FROM MASTER DATA SET *
NOTE ESTABLISH FWA ADDRESSABILITY.
/*COPY SYMBOLIC STRG DEFN FOR TCA*/
/*DEFINE KEY FIELD IN TWA*/
/*COPY SYMBOLIC STRG DEFN FOR FWA*/
/*DEFINE RECORD LAYOUT IN FiA*/
*
/*ASSIGN RECORD IDENT TO KEY FIELD*/
GET RECORD FROM MASTER DATA SET *
*
/*ESTABLISH ADDRESSABILITY FOR FWA*/
The following examples show how to retrieve a single record directly
NOTE ESTABLISH TCA ADDRESSABILITY.
NOTE MOVE RECORD ID TO KEY FIELD.
NOTE ESTABLISH VSiA ADDRESSABILITY.
NOTE ESTABLISH RECORD ADDRESSABILITY.
NOTE MOVE RECORD LENGTH TO aORK AREA.
Chapter 3.2. File Control (DFHFC Macro Instruction) 91
For PL/I:
%INCLUDE DFHTCADS;