Processing a Single Database Record
| This section describes how to process a single database record. A database record comprises a root segment and all of its physically dependent child segments. DL/I calls are introduced in the following sections, and all the samples in those sections are in the standard format shown in Figure 15-1 on page 247. Figure 15-1. Sample Call Format77 GU-FUNC PICTURE XXXX VALUE 'GU ' 01 SSA001-GU-SE1PART. 02 SSA001-BEGIN PICTURE... 02 ... 02 ... 01 IOAREA PICTURE X(256). -------------------------------------------------------------------------- CALL 'CBLTDLI' USING GU-FUNC,PCB-NAME,IOAREA,SSA001-GU-SE1PART. -------------------------------------------------------------------------- STATUS CODES: ------------- Each call example contains three sections:
The last category of status code, labeled "other: error situation", would normally be handled by a status code error routine. For more information, see "Status Code Processing" on page 228. The samples in each of the following sections are presented in COBOL format. The coding of a call in PL/I is described in "PL/I Programming Considerations" on page 263. For information about coding DL/I applications in other languages, see IMS Version 9: Application Programming: Database Manager. DL/I PositioningTo satisfy a call, DL/I relies on two sources of segment identification:
The database position is the knowledge of DL/I of the location of the last segment retrieved and all segments above it in the hierarchy. This database position is maintained by DL/I as an extension of, and reflected in, the PCB. When an application program has multiple PCBs for a single database, these positions are maintained independently. For each PCB, the position is represented by the concatenated key of the hierarchical path from the root segment down to the lowest- level segment accessed. It also includes the positions of non-keyed segments. If no current position exists in the database, then the assumed current position is the start of the database, which is the first physical database record in the database. With HDAM, PHDAM, and DEDB, the first physical database record in the database is not necessarily the root segment with the lowest key value. Retrieving SegmentsYou can retrieve a segment in two basic ways:
If you know the specific key value of the segment you want to retrieve, then the GU call allows you to retrieve only the required segment. If you do not know the key value or do not care, then the GN call retrieves the next available segment that meets your requirements. Get Unique (GU) CallThe basic get unique (GU) call, function code GU Figure 15-2 shows an example of the get unique call. Figure 15-2. Basic Get Unique Call77 GU-FUNC PICTURE XXXX VALUE 'GU The main use of the GU call is to position the application to a database record and obtain a path to the segments. Typically, the GU call is used only once for each database record you want to access. Additional segments within the database record are then retrieved by means of get next calls. You can also use the GU call to retrieve a dependent segment, by adding additional SSAs to the call. For example, if you add a second SSA that specifies the stock location, you would retrieve a STOCK segment below the identified part. If the SSA did not provide a stock location number, this would be the first STOCK segment for this part. Get Next (GN) CallsThe get next (GN) call, function code 'GN' Get next calls can be unqualified or qualified, as described in the next two sections. Unqualified Get Next CallsFigure 15-3 shows a get next call with no SSAs that, if repeated, returns the segments in the database in hierarchical sequence. Only those segments to which the program is defined as sensitive to in its PCB are returned. Figure 15-3. Unqualified Get Next Call77 GN-FUNC PICTURE XXXX VALUE 'GN If the unqualified get next call in Figure 15-3 is issued after the get unique call in Figure 15-2 on page 248, then the unqualified get next call retrieves the first STOCK segment for this part (if one exists). Subsequent calls retrieve all other STOCK, PURCHASE ORDER, and DESCRIPTION segments for this part. After all the segments for this part are retrieved, the next part is retrieved along with its dependent segments, until the end of the database is reached. Special status codes are returned whenever a different segment type at the same level or a higher level is returned. No special status code is returned when a different segment at a lower level is returned. You can check for reaching a lower-level segment type in the segment level indicator in the PCB. Remember, only those segments to which the program is defined as sensitive to in its PCB are available to you. Although the unqualified GN call illustrated in Figure 15-3 on page 249 might be efficient, especially for report programs, you should use a qualified GN call whenever possible. Qualified Get Next CallsA qualified GN call should at least identify the segment you want to retrieve. If you identify the segment in the qualified GN call, you achieve greater flexibility to make database structure changes in the future. Figure 15-4 shows an example of a qualified GN call. If you supply only the segment name in the SSA, then you retrieve all segments of that type from all the database records with subsequent get next calls. Figure 15-4. Qualified Get Next Call77 GN-FUNC PICTURE XXXX VALUE 'GN Repeating the GN call in Figure 15-4 results in retrieving all subsequent PURCHASE ORDER segments of the database, until the end of the database is reached. To limit the retrieval to a specific part, you can add a fully qualified SSA for the PART segment. The fully qualified SSA for the PART segment would be the same SSA used in Figure 15-2 on page 248. Figure 15-5 on page 251 shows an example of a qualified get next call with a qualified SSA. Figure 15-5. Qualified Get Next Call with Qualified SSA77 GN-FUNC PICTURE XXXX VALUE 'GN Recommendation: Primarily use fully qualified get next calls because they always clearly identify the hierarchical path and the segment you want to retrieve. Get Hold CallsTo change the contents of a segment in a database through a replace or delete call, the program must first obtain the segment. The program then changes the segment's contents and requests DL/I to replace the segment in the database or to delete it from the database. Programs use a get hold call to obtain the segment. Get hold calls are similar to get unique and get next calls, except the letter H immediately follows the letter G in the code (for example, GHU, GHN). The get hold calls work exactly as the corresponding get calls for the user. For DL/I, the get hold calls indicate a possible subsequent replace or delete call. After DL/I provides the requested segment to the user, one or more fields, but not the sequence field, in the segment can be changed. After the user has changed the segment contents, your program can call DL/I to return the segment to, or delete it from, the database. If, after issuing a get hold call, the program determines that it is not necessary to change or delete the retrieved segment, the program can proceed with other processing, and the hold is released by the next DL/I call against the same PCB. Updating SegmentsSegments can be updated by application programs and returned to DL/I to be restored in the database with the replace call, function code REPL. Two conditions must be met to successfully update a segment:
Figure 15-6 shows an example of a combination of a GHU call and a REPL call. Notice that the replace call must not specify an SSA for the segment to be replaced. If, after retrieving a segment with a get hold call, the program decides not to update the segment, it need not issue a replace call. Instead, the program can proceed as if it were a normal get call without the hold. Figure 15-6. Sample Combination of a Get Hold Unique Call and a Replace Call77 GHU-FUNC PICTURE XXXX VALUE 'GHU Use the get hold call whenever there is a reasonable chance (5% or greater) that you will change the segment. The difference in performance between the get call and the get hold call is small. Deleting SegmentsTo delete an occurrence of a segment from a database, the segment must first be obtained by issuing a get hold call (GHU, GHN). After the segment is acquired, you can issue a delete call (DLET). If DL/I calls that use the same PCB attempt to intervene between the get hold call and the delete call, the delete call is rejected. Often a program might want to process a segment prior to deleting it. This sequence of processing is permitted as long as the processing does not involve a DL/I call that refers to the same database PCB used for the get hold or delete calls. However, other PCBs can be referred to between the get hold and delete calls. When the user issues a call that has the function DLET, DL/I is advised that a segment is to be deleted. The deletion of a parent deletes all the segment occurrences beneath that parent, whether or not the application program is sensitive to those segments. If the segment being deleted is a root segment, that whole database record is deleted. The segment to be deleted must still be in the IOAREA of the delete call (with which no SSA is used), and its sequence field must not have been changed. Figure 15-7 shows an example of a delete call. Figure 15-7. Sample Combination of a Get Hold Unique Call and a Delete Call77 GHU-FUNC PICTURE XXXX VALUE 'GHU Inserting SegmentsThe insert (ISRT) call adds new segment occurrences to a database. The insert call is used for two distinct purposes:
The processing options field in the PCB indicates whether the database is being added to or loaded. The format of the insert call is identical for either use. When loading or inserting a segment, the last SSA must specify only the name of the segment that is being inserted. The SSA should specify only the segment name, not the sequence field. Thus, an unqualified SSA is always required. Up to a level to be inserted, the SSA evaluation and positioning for an insert call is exactly the same as for a GU call. For the level to be inserted, the value of the sequence field in the segment in the user I/O area establishes the insert position. If no sequence field is defined, then the segment is inserted at the end of the physical twin chain. If multiple non-unique keys are allowed, then the segment is inserted after existing segments with the same key value. Figure 15-8 shows an example of an insert call. The status codes in this example are applicable only to non-initial load inserts. The status codes at initial load time are discussed in "Loading Databases" on page 269. Figure 15-8. Basic Insert Call77 ISRT-FUNC PICTURE XXXX VALUE 'ISRT'. 01 SSA001-GU-SE1PART. 02 SSA001-BEGIN PICTURE x(19) VALUE 'SE1PART You need not check the existence of a segment in the database with a preceding retrieve call. DL/I does that at insert time, and notifies you with an II or GE status code. Checking previous existence is only relevant if the segment has no sequence field. Calls with Command CodesBoth unqualified SSAs and qualified SSAs can contain one or more optional command codes that specify functional variations applicable to either the call function or the segment qualification. Command codes in an SSA are always prefixed by an asterisk (*), which immediately follows the 8-byte segment name. Figure 15-9 illustrates an SSA with command codes D and P. Figure 15-9. Example of an SSA with D and P Command Codes01 SSA001-GU-SE1PART. 02 SSA001-BEGIN PICTURE x(19) VALUE 'SE1PART* D Command CodeThe D command code is the most widely used command code. The D command code tells DL/I to issue path calls. A path call enables a hierarchical path of segments to be inserted or retrieved with one call. The meaning of the D command code is as follows:
Figure 15-10 on page 256 shows an example of a path call. Figure 15-10. Sample Path Retrieve Call77 GU-FUNC PICTURE XXXX VALUE 'GU Figure 15-10 shows a common usage of the path call. Although the retrieve call does not know if the requested part has a separate DESCRIPTION segment (SE1PGDSC), it is retrieved at almost no additional cost, if one exists. P Command CodeThe P command code establishes parentage of present level. Definition: Parentage is a term that describes:
Parentage determines the end of the search, and is in effect only following a successful GU or GN call. Ordinarily, IMS sets parentage at the level of the lowest segment that is accessed during a call. To set parentage at a higher level, use the P command code in a GU, GN, or GNP call. For example, in the following hierarchy:
If a GU call was issued for segment D, the parentage would be set at D so that a GNP call would return segment E. If the GU call was issued for segment D and the P command code was in the SSA for segment B, a GNP call would return segment C. F Command CodeThe F command code allows you to back up to the first occurrence of a segment under its parent. The F command code has meaning only for a get next call. A get unique call always starts with the first occurrence. Command code F is disregarded for the root segment. L Command CodeThe L command code allows you to retrieve the last occurrence of a segment under its parent. This command code should be used whenever applicable. N Command CodeWhen a replace call follows a path retrieve call, DL/I assumes that all segments previously retrieved with the path call are being replaced. If any of the segments have not been changed, and therefore need not be replaced, the N command code can be set at those levels, which tells DL/I not to replace the segment at this level of the path. The status codes returned are the same as for a replace call. Hyphen (-) Command CodeThe hyphen is a null command code, whose purpose is to enable you to reserve one or more positions in a SSA in which a program can store command codes, if they are needed during program execution. Using the hyphen command code simplifies the maintenance of SSAs. Figure 15-11 shows the null command code being used to reserve a position for two command codes. Figure 15-11. Example of a Hyphen (-) Command CodeGU PATIENT**--(PATNO Database Positioning After DL/I CallsDatabase position is used by DL/I to satisfy the next call against a PCB. The segment level, segment name, and the key feedback areas of the PCB are used to present the database position to the application program. These basic rules apply to database positioning after DL/I calls:
When you consider the current position in the database, remember that DL/I must first establish a starting position to be used in satisfying the call. This starting position is the current position in the database for get next calls, and is a unique position normally established by the root SSA for get unique calls. The following are clarifications of current position in the database for special situations:
You can always reestablish your database positioning with a get unique call that specifies all the segment key values in the hierarchical path. It is recommended that you use a get unique call after each not found condition. Using Multiple PCBs for One DatabaseUse different PCBs whenever there is a need to maintain two or more independent positions in one database. Using different PCBs avoids the need to issue additional get unique calls to switch forward and backward from one database record or hierarchical path to another. There are no restrictions as to the call functions available in these multiple PCBs. However, to avoid position confusion in the application program, you should not apply changes by using two PCBs to the same hierarchical path. Limit the updates to one PCB unless this causes additional calls. System Service CallsIn addition to call functions that manipulate database segments, DL/I provides special system service calls. The most common system service calls are: Statistics (STAT)
Checkpoint (CHPK)
Restart (XRST)
The XRST and CHKP calls are discussed in more detail in "Using Batch Checkpoint/Restart" on page 275. Processing GSAM DatabasesAll access to GSAM databases is done through DL/I calls. DL/I checks to determine whether a user request is for a GSAM database. If the request is for a GSAM database, control is passed to GSAM, which is resident in the user region. If the request is not for a GSAM database, control is passed to DL/I, and standard hierarchical processing results. The format of the CALL statement to access a GSAM database is: CALL 'CBLTDLI' USING call-func,pcb-name,ioarea. call-func
pcb-name
ioarea
Table 15-4 contains the status codes that are associated with processing GSAM databases.
Record FormatsRecords can be fixed length or variable length, blocked or unblocked. Records must not have a sequence key. The record in the IOAREA includes a halfword record length for variable-length records. The use of GSAM data sets in a checkpoint/restart environment is discussed further in "Using Batch Checkpoint/Restart" on page 275. |
: succesfull call --: exceptional but correct condition other: error condition 
='. 02 SSA001-FE1PGPNR PICTURE X(8). 02 SS1001-END PICTURE X VALUE ')'. 01 IOAREA PICTURE X(256). -------------------------------------------------------------------------- MOVE PART-NUMBER TO SSA001-FE1PGPNR. CALL 'CBLTDLI' USING GU-FUNC,PCB-NAME,IOAREA,SSA001-GU-SE1PART. -------------------------------------------------------------------------- STATUS CODES: ------------- 
=
EAN: 2147483647
Pages: 226