1. Group several random requests into ascending key sequence.
2. Issue a DFHFC TYPE=SE~L macro instruction which positions to the first required record. TO achieve this, the record
identification field pointed to by the RDIDADR operand should be initialized to the key of the required record.
3. Prior to each DFHFC TYPE=GETNEXT macro instruction, place the key of the next required record into the record identification field.
This procedure allows quick random access to a VSAM data set by reducing index search time. When the record having the highest key has been retrieved, an ESETL or RESETL should be issued to terminate or reset the operation.
Initiate Sequential Retrieval (SETL)
The application programmer initiates a browse operation on a data set by issuing the
DFHFC TYPE=SETL,
macro instruction. This macro instruction is used to establish the position within the data set where the browse operation is to begin.
It must be issued before any DFHFC TYPE=GETNEXT macro instruction. No data is available until a DFHFC TYPE=GETNEXT is used.
Recall that an application prcgram communicates to CICS/VS the identity of a specific record required in an input/output operation by means of a record identification field established for the data set.
(See "Record Identification Field" in Chapter 11.) For an ISAM data set, the browse operation begins at the first record with a key equal to or greater than the key provided in the record identification field for the data set. This key rray be either a specific (com~lete) key or
*
a generic (partial) key. For example, a complete key of D642BR17 causes sequential processing to begin at the first record with a key equal to or greater than that key. A generic key is one in which the application programmer supplies only the significant characters of a desired group of keys, padding the remainder of the key field with blanks or binary zeros. A generic key of D6420000 causes sequential processing to begin at the first record with a key whose first four characters are equal to or greater than D642xxxx, regardless of the character represented by each x. A key field of all binary zeros causes sequential processing to begin at the first logical record of the data set.
For a DAM data set, the record identification field must contain a specific block reference (for exam~le, TTR or MBBCCHHR as explained in Chapter 11) which conforms to the addressing method defined for that data set. Processing begins with the specified block and continues wi th each subsequent block until the browse operation is termina'ted.
If the DAM data set ~ontains blocked records, processing begins at the first logical record of the first block and continues with each
subsequent logical record.
For a VSAM data set, the contents of the record identification field may be either a key or a relative byte address. If the field contains a relative byte address, the browse operation begins Qt the location identified. If the fieldcor.tains a key, i t may be either specific or generic. If the key is generic, the length of the partial key is specified in the first byte of the record identification field. In
either case, the application programmer can specify that the browse operation is to begin at the first record having a key (1) equal to the key in the record identification field (for generic, compared on only the number of bytes specified), or (2) equal to or greater than the key in the record identification field (again, for generic, compared on only the bytes specified) •
When the DFHFC TYPE=SETL macro instruction is used, the application programmer must provide instructions that do the following:
• Symbolically define the FWA by (1) copying the appropriate CICS/VS control section storage definition (DFHFWADS), and (2) providing his own storage definiticn for the user's section of the FWA •
• Establish addressability for the FWA by specifying a symbolic base address for the FWA, typically following the DFHFC macro
instruction. (The address of the FWA, provided by CICS/VS at
TCAFCAA, must be placed at FWACBAR upon normal return from execution of the SETL macro instruction.)
In most cases, records retrieved during a browse operation are returned to the application ~rogram in a file work area (FWA). In locate mode the addresses of the logical record are passed in the VSWA.
The FWA allocated by CICS/VS following a SETL request is unique for the duration of that particular browse operation. If the application program issues another SETL request, for the same or another data set, a different FWA is created by CICS/vS. Thus i t is possible for a single application program to concurrently browse the same data set at several different locations.
Note that during a browse operation on a segmented data set, the original FWA (that is, the one allocated by CICS/VS in response to the SETL request) may be replaced with a different FWA i f a segment set specified in a GETNEXT request requires a larger FWA than the segment set specified in the SETL request. In this situation, the application programmer should not assume that the same FWA is used for all GETNEXT requests. The address of the utilized FWA is available at TCAFCAA upon return from a GE~NEXT request.
CICS/VS performs the follcwing services in response to a DFHFC TYPE=SETL macro instruction:
1. Acquires the main storage I/O areas and work areas to be associated with this browse operation
2. Preserves the segment set name (if any) as the default segment set name to be used i f none is specified in subsequent GETNEXT requests
3. Returns the address of the allocated FWA in TCAFCAA for other than locate-mode nonsegmented VSAM data set processing; returns the address of the allocated VSWA that will contain the VSAM buffer-area address of each retrieved record for locate-mode nonsegmented VSAM data set processing
The information supplied by the user in the record identification field is preserved by CICS/vS for use When GETNEXT requests are issued.
Since CICS/VS places into this field the identification of each record retrieved in response to a subsequent GETNEXT request, the field should not be released by the application program.
The information placed into the record identification field by CICS/VS is always in a form which completely identifies the record.
For example, assume a browse operation is to start with the first logical record of a blocked, key~d DAM data set. E~fore issuing the 84 CICS/VS Application Programmer's Reference Manual
DFHFC TYPE=SETL macro instruction, the application programmer should place the TTR (assuming that is the addressing method) of the first block into the Record Identification field. After executing each DFHFC TYPE=GETNEXT macro instruction, CICS/vS places the complete logical
record identification into the record identification field. After the first GETNEXT, the record identification field might contain
X'00010504' GETNEXT request, the record identification field contains
X'00020201'
ESTAELISH ADDRESSABILITY FOR FWA ENTRY TO ERROR ROUTINE
02 FWACBAR PICTURE S9(8) USAGE IS COMPUTATIONAL.
01 DFHTCADS COpy DFH'lX."!ADS.
02 KEYF PICTPRE X(8) •
NOTE ESTABLISH TCA ADDRESSABILITY.
* *
*
r - - - - - - - - -
-MOVE 'JONES' TO KEYF.
START.
DFHFC TYPE=SETL, DATAS ET=MAST ER , RDIDADR=KEYF, NOTOPEN=ERROR MOVE TCAFCAA TO FWACBAR.
ERROR.
For PL/I:
%INCLUDE DFHTCADS;
02 KEYF CHAR (8) ;
%INCLUDE DFHFWADS;
02 RECORD CHAR (350) ; KEYF='JONES' ;
START:
DFHFC TYPE=SETL, DATAS ET=MAST ER , RDIDADR=KEYF, NOTOPEN=ERROR FWACBAR=TCAFCAA;
ERROR:
INITIATE BROWS E CHECK FOR ERRORS
/*COPY SYMBOLIC STRG DEFN FOR TCA*/
/*COPY SYMBOLIC STRG DEFN FOR FWA*'/
/*DEFINE RECORD LAYOUT IN FWA*/
INITIATE BROWS E CHECK FOR ERRORS
Retrieve Next sequential Record (GETNEXT)
Once the application programmer has issued a DFHFC TYPE=SETL macro instruction to initiate a browse operation, the next (or first)
sequential record can be obtained by issuing the DFHFC TYPE=GETNEXT,
macro instruction. When the first GETNEXT request is issued following a SETL request for an ISAM data set, CICS/VS acquires the first logical record with a key equal to or greater than the key presented by a
previous SETL; for a DAM data set, CICS/VS acquires the first logical record specified by the user. Each subsequent GETNEXT request, whether for an ISAM or a DAM data set, causes CICS/vS to acquire the next
logical record in sequence.
When VSAM is used, the application programmer can specify that a browse operation begin at a particular relative byte location or with a record identified by a key. In the former case, the first GETNEXT request retrieves that record. Each succeeding GE~EXT retrieves the next logical record in sequence.
86 CICS/VS Application Programmer's Reference Manual
* *
*
* *
*
*
If a key is specified fer a VSAM data set, i t may be either specific or generic, and the application Frogrammer can specify that the search begin (1) at a record having a key equal to the specific or generic key, or (2) at a record having a key equal to or greater than the specific or generic key. The effects of GETNEXT macro instructions are as described below.
Before issuing the DFHFC 'IYPE=GETNEXT macro instruction, the application programmer must place the address of the FWA associated with the particular operation in TCAFCAA. If the application program has initiated multiple browse operations, i t must keep track of the FWA associated with each operatien and refer to a specific FWA when requiring services related to that browse. Similar requirements apply, but pertain to the address of a specific VSWA when locate-mode
processing of VSAM nonsegmented records is utilized.
CICS/VS performs the following services in response to a DFHFC TYPE=GETNEXT macro instruction referring to an ISAM, VSAM, or DAM data set:
1. Retrieves the next sequential record and places i t in the FWA specified by the user at TCAFCAA
2. Places the record identification (key, block identification, or the like) of the record just retrieved into the record
identification field specified in the DFHFC TYPE=SETL request initiating the browse
If the user issues a DFHFC TYPE=GET,TYPOPER=UPDATE request on the record returned in response to a DFHFC TYPE=GETNEXT request, the address of the record identification field can be specified in the DFHFC
TYPE=GET request.
The first DFHFC TYPE=GETNEXT macro instruction referring to a VSM1 data set retrieves the record located in response to the DFHFC TYPE=SETL instruction initiating the browse. On a subsequent GETNEXT, CICS/VS checks the contents of the record identification field set aside for
records of the data set. If this field contains the. identification of the record previously received, CICS/vS retrieves the next logical record in sequence and places the identification of that record in the record identification field. sequential retrieval such as described above for ISAM and DAM data sets then occurs.
I t is possible, however, when using VSAM data sets, for the application programmer to utilize a skip-sequential processing
capability. All that is needed is to place the identification of the next record desired into the record identification field prior to issuing a GETNEXT request. If, upon checking this field, CICS/vS determines that its contents haVE been changed by the application
program, CICS/VS accesses the record having the identification currently stored in the record identification field. This record need not be the next sequential record in the data set. This skip-sequential processing capability is available only for VSAM data sets.
When VSAM skip-sequential processing is used, the record
identification placed in the record identification field before issuing the GETNEXT request must be of the same form as that specified in the SETL or last RESETL request for this browse operation. That is, if the SETL or last RESETL specified a generic key, then the new record identification must be a generic key. I t need not be the sanle length as that specified in the SETL or last RESETL. If the SETL or last RESETL specified an RBA, the new identification must be an RBA. Note that if the SETL or last RESETL specified an equal search (FKEQ or GKEQ), a GETNEXT request using skip-sequential processing may result in a NOTFND (record not found) condition.
In addition, CIC8/VS can perform the following services, depending
(For more about segmented records, see "Segmented Records" in Chapter 11 and the explanation of the SEGSET operand under "DFHFC Macro
ESTABLISH FWA BASE REGISTER
RESTORE FWA ADCRESS
GET NEXT SEQUENTIAL RECORD
ASSURE ADDRESSABILITY IF SEGMENTED
RESTORE FWA ADCRESS GET NEXT RECORD WITH SEGMENT B
ASSURE ADDRESSABILITY IF SEGMENTED
02 FWACBAR PICTURE S9(8) USAGE IS COMFUTATIONAL.
NOTE DEFINE BASE REGISTER FOR FWA.
01 DFHTCADS COpy DFHTCADS. NOTE COPY SYMBOLIC STRG DEFN FOR TCA.
02 KEYF PICTURE 89(18) USAGE IS COMPUTATIONAL.
NOTE DEFINE KEY FIELD IN TWA.
88 CICS/VS Application Programmer's Reference Manual
* *
*
*
01 DFHFWADS COPY DFHFWADS.
02 RECORD PICTURE X(350).
PROCEDURE DIVISION.
MOVE CSACDTA TO TCACBAR.
MOVE 0 TO KEYF.
INITIAL.
DFHFC TYPE=SETL, DATASET=MASTER, SEGSET=A,
RDIDAl)R=KEYF MOVE TCAFCAA TO FWACBAR.
MOVE FWACBAR TO TCAFCAA.
DFHFC TYPE=GETNEXT
MOVE FWACBAR TO TCAFCAA.
DFHFC TYPE=GETNEXT, SEGSET=B MOVE TCAFCAA TO FWACBAR.
For
PL/I:%INCLUDE DFHTCADS;
02 KEYF BINARY FIXED(8,0) ;
%INCLUDE DFHFWADS;
02 RECORD CHAR(350) ;
KEYF=O;
INITIAL:
DFHFC TYPE=SETL, DATASET=MASTER, SEGSET=A,
RDIDADR=KEYF FWACBAR=TCAFCAA;
TCAFCAA=FWACBAR;
DFHFC TYPE=GETNEXT
NOTE COPY SYMBOLIC STRG DEFN FOR FWA.
NOTE DEFINE RECORD LAYOUT IN FWA.
NOTE ESTABLISH TCA ADDRESSABILITY.
NOTE START AT BEGINNING OF DATA SET.
INITIATE BROWSE
SET DEFAULT SEGMENT SET
NOTE ESTABLISH FWA ADDRESSABILITY.
GET NEXT SEQUENTIAL RECORD.
GET NEXT RECORD WITH SEGMENT B
NOTE POSSIBLE NEW FWA.
/*copy SYMBOLIC STRG DEFN FOR TCA*/
/*DEFINE KEY FIELD IN TWA*/
/*COPY SYMBOLIC STRG DEFN FOR FWA*/
/*DEFINE RECORD LAYOUT IN FWA*/
/*START AT BEGINNING OF DATA SET*/
INITIATE BROWSE
SET DEFAULT SEGMENT SET
/*ESTABLISH,FWA ADDRESSABILITY*/
GET NEXT SEQUENTIAL RECORD
* *
*
*
* *
*
TCAFCAA=FWACBAR;
Terminate sequential Retrieval (ESETL)
The application programmer can terminate a browse operation by issuing the
DFHFC TYPE=ESETL,
*
macro instruction. Before the macro is issued, the programmer must ensure that TCAFCAA contains the address of the file work area (FWA) associated with the browse operation he wishes to terminate. When
locate-mode processing of VSAM nonsegmented records is utilized, TCAFCAA must contain the address of the VSAM work area (VSWA) associated with FOR SECOND BROWSE OPERATION ASSIGN FWA BASE REGISTER
DEFINE FWA SYMEOLIC STORAGE DEFN DEFINE RECORD
MVC TCAFCAA, FWACELL 1 MOVE BROWSE 1 FWA ADDR TO TCA ISSUE ESETL MACRO INSTRUCTION MOVE BROWSE 2 FWA ADDR TO TCA ISSUE ESETL MACRO INSTRUCTION DFHFC TYPE=ESETL
90 CICS/VS Application Programmer's Reference Manual
MOVE FWACELL1 TO ':OCAFCAA.
DFHFC TYPE=ESETL MOVE FWACELL2 TO TCAFCAA.
DFHFC TYPE=ESETL For PL/I:
%INCLUDE DFHTCADS;
02 FWACELL1 POINTER;
02 FWACELL2 POINTER;
%INCLUDE DFHFWADS;
02 RECORD CHAR(350) ;
TCAFCAA=FWACELL1;
DFHFC TYPE=ESETL TCAFCAA= FWACELL2 ;
DFHFC TYPE=ESETL
NOTE PREPARE TO END FIRST BROWSE.
TERMINATE FIRST BROWSE.
NOTE PREPARE TO END 2ND BROWSE.
TERMINATE SECOND BROWSE.
/*CCPY SYMBOLIC STRG DEFN FOR TCA*/
/*COPY SYMBOLIC STRG CEFN FOR FWA*/
/*DEFINE RECORD LAYOUT IN FWA*/
/*MOVE BROWSE1 FWA ADDR TO TCA*/
/*MOVE BROWSE2 FWA ADDR TO TCA*/
Reset sequential Retrieval (RESETL)
Once a browse operation has been initiated, the application
programmer may, at any time ~rior to issuing an ESETL request for the browse, reset the search argument to some record other than the next sequential record in the data set. The default segment set name and (for a VSAM data set) the type of search argument used in retrieving records can also be reset by issuing the
DFHFC TYPE=RESETL,
macro instruction. Prior to issuing the request, the application
programmer should place the address of the appro~riate FWA into TCAFCAA and the new record identification in the record identification field specified in the original SETL request.
The use of the RESETL macro instruction allows the application programmer to avoid issuing an ESETL request followed by another SETL request, and causes CICS/vS to use the same I/O and work area. Upon return from the RESETL request, TCAFCAA contains the address of a new FWA which the user can use far the browse operation.
The RESETL request allows the user to "skip" through his data set in a browse operation with minimal oveIhead. A similar capability is also available to VSAM users through the GETNEXT instruction.
The following examples show how to reset the search argument and the default segment set for ·a brcwse operation. (For more about segmented records, see "segmented Records" in Chapter 11 and the explanation of the SEGSET operand under nDFHFC Macro Instruction" in Chapter 7.)
*
For AsseIl'bler
ESTABLISH ADDRESSABILITY TO FWA
STORE FWA ACDR IN TCA
ESTABLISH NEW SEARCH ARGUMENT
ISSUE RESETL MACRO *
NEW SEGSET ID
ESTABLISH ADDRESSABILITY TO FWA
02 FWACBAR PICTURE S9(8) USAGE IS COMPUTATIONAL.
01 DFHFWA REDEFINES DFHFWADS.
02 CICS/vS/VS~ART PICTURE X(*).
NOTE ESTA~ISH ADPRESSABILITY TO FWA.
NOTE STQRE FWA ADDRESS IN TCA.
NOTE ESTABLISH NEW'SEARCij ~RGUMENT.
ISSUE RESETL MACRO INSTRUCrIO~ * NEW SEGSET ID
NOTE E~TAELISH ADDRESSABI~ITY TO FWA.
92 CICS/VS Application Programmer's Reference Manual
For ~:
~INCLUDE PFHTCADS; /*COPY SYMBOLIC STRG DEFN FOR TCA*/
02 KEYF BINARY FIXED(8,0) ; /*DEFINE KEY AS BINARY*/