Additional facilities available with DBCTL include application program access to DEDBs, a number of additional commands, calls, and keywords, increased data availability, and the ability to use BMPs.
With DBCTL, your EXEC DLI and CALL DL/I application programs can access DEDBs. For an overview of the benefits of using DEDBs (including subset pointers), see Access to data entry databases (DEDBs).
For programming information on using subset pointers and EXEC DL/I keywords, see the IMS Application Programming: EXEC DLI Commands manual and the IMS Application Programming: DL/I Calls manual manuals.
With DEDBs, you can set and use up to eight subset pointers for each direct dependent segment type in the database description (DBD). You must also define in the PSB, using the SENSEG statement, which subset pointers your program will use. You can then use subset pointers from within the application program together with certain command codes. Keywords and corresponding command codes tells you which subset pointers you can use with which command codes.
You can use a number of additional EXEC DLI keywords in a CICS-DBCTL environment; they are described in the headings that follow. Each of these keywords has a corresponding CALL DL/I command code. These are shown in Keywords and corresponding command codes.
The LOCKED keyword corresponds to the Q command code. You use either of these to reserve a segment so that other programs cannot update until after you have finished with it. You can associate the Q command code with a 1-character field, from A through J, but the LOCKED keyword cannot take an argument. The LOCKCLASS keyword enables you to make full use of the DEQ command.
You use the LOCKCLASS keyword, with retrieve requests only, in the same situations that the LOCKED keyword can be used. However, the LOCKCLASS keyword can take a 1-character argument, in the range B to J inclusive. You cannot use LOCKED and LOCKCLASS for the same segment.
The MOVENEXT keyword sets the subset pointer to the segment following the current segment. You can only use it with a DEDB that uses subset pointers. You can use it when retrieving, inserting, or replacing a segment. You cannot use it with a SETZERO keyword for which you have specified subset pointer values, or with the LOCKED or LOCKCLASS keywords.
MOVENEXT, which corresponds to the M command code, can take an argument, which can be a constant of up to 8 bytes or a variable of exactly 8 bytes. Each byte indicates a subset pointer and should be a single number from 1 through 8. If you use a variable that is longer than the number of subset pointers to be referenced, you should left justify the data and set the rest of the variable to blanks (for example, X'F1F3404040').
The GETFIRST keyword, which corresponds to the R command code, causes the first segment in a subset to be retrieved or inserted. You can only use it when retrieving or inserting a segment in a DEDB that uses subset pointers. You can only use one GETFIRST keyword with each parent or object segment. You cannot use the GETFIRST keyword with the FIRST, LOCKED, or LOCKCLASS keywords.
GETFIRST can take a single argument, which can be a constant or a 1-byte variable. The value of the argument must be a number from 1 through 8, in character form, that indicates a subset pointer.
The SET keyword, which corresponds to the S command code, causes the appropriate subset pointer to be set unconditionally to the current position, in a DEDB with subset pointers. Use the SET keyword when retrieving, inserting or replacing a segment. You cannot use it with a SETZERO keyword that has the same subset pointer value, or with the LOCKED or LOCKCLASS keywords.
SET can take an argument, which can be a constant of up to 8 bytes, or a variable of exactly 8 bytes. Each byte indicates a subset pointer and must be a single integer, in character form, from 1 through 8. If you use a variable that is longer than the number of subset pointers to be referenced, you should left justify the data and set the rest of the variable to blanks (for example, X'F1F3404040').
The SETCOND keyword, which corresponds to the W command code, causes the appropriate subset pointer to be set only if it is not already set to a segment. You can only use it when processing a DEDB with subset pointers. You can use SETCOND when retrieving, inserting, or replacing a segment. You cannot use it with the SETZERO keyword that has the same subset pointer value, or with the LOCKED or LOCKCLASS keywords.
SETCOND can take an argument, which can be a constant of up to 8 bytes or a variable of exactly 8 bytes. Each byte indicates a subset pointer and must be a single number, in character form, from 1 through 8. If you use a variable that is longer than the number of subset pointers to be referenced, you should left justify the data and set the rest of the variable to blanks (for example, X'F1F3404040').
The SETZERO keyword, which corresponds to the Z command code, causes the appropriate segment subset pointer to be set to zero. You can only use it with DEDBs that use subset pointers. You can use SETZERO when retrieving, inserting, replacing, or deleting a segment. You cannot use it with SET, SETCOND, or MOVENEXT keywords that have the same subset pointer values. You cannot use it with the LOCKED or LOCKCLASS keywords.
SETZERO can take an argument, which can be a constant of up to 8 bytes or a variable of exactly 8 bytes. Each byte indicates a subset pointer and must be a single number, in character form, from 1 through 8. If you use a variable that is longer than the number of subset pointers to be referenced, you should left justify the data, and set the rest of the variable to blanks (for example, X'F1F3404040').
If your application program issues a system service request in an EXEC DLI environment, you do not need to specify the PCB number, because the IOPCB is assumed for this type of request. However, if you are using one of the following EXEC DLI system service requests:
first issue a PSB schedule command specifying the SYSSERVE keyword. See PSB schedule command and call for the format of the schedule request.
Table 5 lists EXEC DLI keywords and corresponding DL/I CALL command codes that are valid in a DBCTL environment.
EXEC DLI keyword | DL/I CALL command code | Purpose |
---|---|---|
KEYS | C | Using the concatenated key of a segment to identify the segment. |
INTO or FROM specified on segment level to be retrieved or inserted | D | Retrieving or inserting a sequence of segments in a hierarchic path using only one request, instead of having to use a separate request for each segment (path call or command). |
FIRST | F | Backing up to the first occurrence of a segment under its parent when searching for a particular segment occurrence. Disregarded for a root segment. |
LAST | L | Retrieving the last occurrence of a segment under its parent. |
MOVENEXT 1 | M 1 | Moving a subset pointer to the next segment occurrence after your current position. |
Leaving out the SEGMENT option for segments you do not want replaced | N | Designating segments you do not want replaced, when replacing segments after a get hold request. Used when replacing part of a path of segments. |
SETPARENT | P | Setting parentage at a higher level than usual. (It is usually the lowest SSA level of the call.) |
LOCKED 2
LOCKCLASS 2 |
Q 2 | Reserving a segment so that other programs will not be able to update it until after you have finished processing and updating it. |
GETFIRST 1 | R 1 | Starting search with the first segment occurrence in a subset. |
SET 1 | S 1 | Unconditionally setting a subset pointer to the current position. |
No EXEC equivalent | U | Limiting the search for a segment to the dependents of the segment occurrence on which position is established. |
CURRENT | V | Using the current position at this hierarchic level and above as qualification for the segment. |
SETCOND 1 | W 1 | Setting a subset pointer to your current position, if the subset pointer is not already set. |
SETZERO 1 | Z 1 | Setting a subset pointer to zero. |
With DEDBs, you can use the position (POS) command and call to retrieve the location of a specific sequential dependent segment or the location of the last inserted sequential dependent segment. The POS command and call also provides information about unused space.
You can specify only one SSA with the POS request; that is, either the root segment, or a sequential dependent segment. You can use POS to locate a specific sequential dependent segment when you already have a valid position of a root segment. If you do not already have one, you must first issue a separate POS request, or other request, to establish the position of a root segment.
The format of the POS command is:
EXEC DLI POS|POSITION
USING PCB(n)
INTO(data-area)
[KEYFEEDBACK(area)[FEEDBACKLEN(expression)]]
[SEGMENT(name)|SEGMENT((area))]
[WHERE(qualification_statement)[FIELDLENGTH(expression)]]
The format of the POS call is:
CALL 'CBLTDLI' USING POS,dedb_pcb,i/o_area[,ssa]
See Keywords and corresponding command codes and Comparing EXEC DLI commands and DL/I calls for brief comparisons of commands and calls. For further guidance on the differences between commands and calls, see the IMS Application Programming: Design Guide.
Addressing mode (AMODE) refers to the address length that a program is prepared to handle: 24-bit addresses, 31-bit addresses, or both (ANY). Programs with an addressing mode of ANY must have been designed to receive control in either 24- or 31-bit addressing mode.
Residency mode (RMODE) specifies where a program is expected to reside in virtual storage. RMODE 24 indicates that a program is coded to reside in virtual storage below 16MB. RMODE ANY indicates that a program is coded to reside anywhere in virtual storage.
See the OS/390 MVS Extended Addressability Guidefor more information on AMODE and RMODE. See also the appropriate programming guides for COBOL and PL/I for guidance on placing parameters above or below the line.
With remote DL/I and DBCTL, programs can be AMODE(31) RMODE(any) with parameters above the 16 MB line, for both DL/I call and command level.
DBCTL supports enhanced scheduling. That is, PSB scheduling completes successfully, even if some of the full function databases or DEDB areas it requires are not available. Full function databases that have been stopped or locked by the commands /STOP, /DBRECOVERY, or /LOCK, or that are unavailable for update because a /DBDUMP command has been issued, do not cause scheduling failures. Instead, the application program is prevented from accessing only the unavailable database(s) or area(s). Application programs can have read access to databases that have been made unavailable for update by the /DBDUMP command. If a program issues a call to an unavailable database or area, a transaction abend is issued. To avoid this happening, you can issue requests, after a PSB has been scheduled, to obtain information regarding the availability of each database and to indicate that your program will handle data availability status codes. These requests are described in Obtaining information about database availability and Accepting database availability status codes.
A PSB scheduling request places data availability status codes in each of the DB PCBs. You can use DL/I requests to obtain and refresh this information, as described below.
In a command-level environment, issue the following command after a PSB schedule request for each PCB:
EXEC DLI QUERY PCB(n)
where n is the number of a PCB.
This obtains the status code and other information in the DL/I interface block (DIB). You should get one of the following values in the DIB:
DIBDBORG, which is returned when DIBSTAT has been set to NA, NU or (blanks). DIBDBORG contains one of the following values describing the database organization:
DIBDBDNM, which is returned when DIBSTAT has been set to NA, NU or blanks, and contains the DBDNAME. You can refresh these status codes using the command:
EXEC DLI REFRESH DBQUERY
Application programs using the DL/I CALL interface can access the PCB status codes directly. You can refresh these status codes using the INIT call as follows:
CALL 'CBLTDLI' USING INIT,i/o pcb,i/o_area
where i/o_area contains a string in the format LLZZcharacter_string.
The data availability status codes used in this context are:
You can use DL/I requests to indicate that your application program is prepared to accept and handle database availability status codes for DL/I calls, as described in ACCEPT STATUSGROUP command and INIT call--format for accepting status codes. These status codes may have been issued because PSB scheduling has completed without all of the referenced databases being available.
For command level application programs, use:
EXEC DLI ACCEPT STATUSGROUP('A')
For call level application programs, use:
CALL 'CBLTDLI' USING INIT,i/o pcb,i/o_area
where i/o_area contains a string in the format LLZZcharacter_string.
If you have used ACCEPT STATUSGROUP, and a DL/I request tries to access a database or a DEDB area that is not available after PSB schedule, DBCTL returns a status code instead of abending the transaction. If you have not used ACCEPT STATUSGROUP, the transaction will be abnormally terminated with ADCI if it tries to access unavailable data. (See Summary of DBCTL abends and return codes for details of accompanying return codes.)
See the IMS Application Programming: EXEC DLI Commands manual or the IMS Application Programming: DL/I Calls manual manuals for programming information on status codes.
Although a PSB can contain PCBs for GSAM and MSDB databases, and the PSB can be scheduled, programs using DBCTL (or any other kind of CICS-DL/I program) cannot access those GSAM or MSDB databases online from CICS. Access to such databases is by means of batch and BMPs only. See I/O PCB for information on the option SCHD, which you can use to state whether you require an input/output PCB (I/O PCB).
The following DEDB status codes are returned when DL/I backout has taken place: BB, FD, FR, FS. If you receive one of these status codes, it is as if any update requests you issued to full function databases or to DEDBs in the same UOW had not taken place.
If you are using EXEC DLI, these status codes are, as usual, accompanied by a DHBB, DHFD, DHFR, or DHFS abend.
If you are using CALL DL/I and if you want any other resources you may have been updating in the same UOW to be backed out, issue an EXEC CICS ABEND request or a SYNCPOINT ROLLBACK command.
Batch message processing programs (BMPs) are application programs that perform batch type processing online and can access databases controlled by DBCTL. You can run the same program as a BMP or as a batch program. Figure 32 shows the kind of data BMPs can access. See the IMS Application Programming: Design Guide for further guidance on using BMPs.
A PSB used in a DBCTL environment can contain any of the following PCB types:
With DBCTL, a CICS online application program receives, by default, a DB PCB as the first PCB in the parameter list passed to it after scheduling.
With the EXEC DLI interface, in order to use system service requests, you specify the SYSSERVE keyword on the SCHD command to indicate that your application program can handle an I/O PCB. In an EXEC DLI environment, the SYSSERVE keyword does not change the PCB numbering, which means that your first PCB is still the DB PCB, and you do not need to specify a PCB number when you issue a system service request.
With the DL/I CALL interface, in order to use system service requests, you use the IOPCB parameter on the PCB to indicate that your application program can handle an I/O PCB. The I/O PCB will then be the first PCB in the parameter address list passed back to your application program.
PSBs used in a DBCTL environment will be of the following form:
[IOPCB]
[Alternate TP PCB ... Alternate TP PCB]
[DBPCB ... DBPCB]
[GSAMPCB ... GSAMPCB]
Each PSB must contain at least one PCB. A DB PCB can be a full function PCB, or a DEDB PCB.
This section summarizes information concerning I/O PCBs and alternate PCBs in the supported environments. Read it if you intend to issue system service requests.
The first PCB in your PCB address list always refers to the first database PCB (DB PCB) whether or not you specify the SYSSERVE keyword.
If you specify the IOPCB option on the PCB call, the first PCB in your PCB address list will be the I/O PCB, followed by any alternate PCBs, followed by the DB PCBs.
If you do not specify the IOPCB option, the first PCB in your PCB address list will be the first DB PCB.
The PCB list always contains the address of the I/O PCB, followed by the addresses of any alternate PCBs, followed by the addresses of the DB PCBs.
Alternate PCBs are always returned to batch programs irrespective of whether you have specified CMPAT=Y. The I/O PCB is returned depending on the CMPAT option, as follows:
If you specify CMPAT=Y, the PCB list contains the address of the I/O PCB, followed by any alternate PCBs, and then the DB PCBs.
If you do not specify CMPAT=Y, the PCB list contains the addresses of any alternate PCBs followed by the addresses of the DB PCBs.
Table 6 summarizes the I/O PCB and alternate PCB information.
Environment | EXEC DLI: I/O PCB count included in PCB(n) | EXEC DLI: Alternate PCB count included in PCB(n) | CALL DLI: I/O PCB address returned | CALL DLI: Alternate PCB address returned |
---|---|---|---|---|
CICS DBCTL: SCHD request issued without the IOPCB or SYSSERVE option | No | No | No | No |
CICS DBCTL: SCHD request issued with the IOPCB or SYSSERVE for a CICS DBCTL request or for a function shipped request which is satisfied by a CICS system using DBCTL | No | No | Yes | Yes |
BMP | Yes | Yes | Yes | Yes |
Batch: CMPAT=N specified | No | Yes | No | Yes |
Batch: CMPAT=Y specified | Yes | Yes | Yes | Yes |
The format of the schedule command is:
EXEC DLI SCHD PSB(name)[SYSSERVE]
Specifying SYSSERVE does not affect the PCB number you specify in the USING PCB keyword because PCB(1) will always refer to the first DB PCB. The application program must establish addressability to the I/O PCB. See the IMS Application Programming: Design Guide for further guidance on doing this.
The format of the schedule call is:
CALL 'CBLTDLI' USING PCB ,psbname,uibptr[,sysserve]
where sysserve is an optional 8-byte variable, set to either IOPCB or NOIOPCB.
Almost all the new DL/I calls supported in the CICS-DBCTL environment require an I/O PCB. The two exceptions are the ROLS call, which can use a DB PCB, and the POS call, which uses a DEDB PCB.
When a PSB schedule request fails (for example, because a database is unavailable), CICS abends the transaction with a DHxx abend code. In a production system, PSB schedule request failures are more likely to be caused by unavailability of a database than by application coding errors, which means that end users may see DHxx abends unnecessarily. To prevent this happening, you can use the EXEC DLI SCHD PSB keyword, NODHABEND, which specifies that no DHxx abends are issued for that PSB schedule request. Instead, the xx value is returned to the application program in DIBSTAT, enabling the application to deal with the situation in a more user-friendly way, and avoiding the need to code global HANDLE ABENDs (EXEC DLI does not support HANDLE CONDITION).
The DEQ (dequeue) request releases segments that were retrieved using the LOCKCLASS keyword or the Q command code.
The LOCKED keyword cannot take an argument, and cannot be used with DEQ. (Segments locked using the LOCKED keyword are released when a SYNCPOINT is taken.) Instead, you use LOCKCLASS with DEQ, which can take a 1-character argument in the range B to J inclusive. (These keywords correspond to the Q command code, which you can associate with a 1-character field in the range A to J.) You cannot use LOCKED and LOCKCLASS for the same segment. Using LOCKCLASS or Q on retrieval requests enables you to reserve segments for exclusive use by your transaction. No other transaction is allowed to update these reserved segments until your transaction reaches a syncpoint, or the DEQ request has been issued, when the reserved segments are released. This means that your application can leave these segments and retrieve them later without them being changed in the meantime.
The format of the DEQ command is:
where data_value is a 1-byte alphabetic character in the range B to J.
The format of the DEQ call is:
where function is the address of a 4-byte area that contains the value of the DEQb function, i/o pcb is the name of the I/O PCB (mandatory), and i/o_area is a 1-byte alphabetic character in the range A to J.
You can use the LOG request online when you want a record to be written from an application program to the IMS log. Your program can specify whatever information you want to be on the log. You may prefer to use it instead of EXEC CICS journal commands so that all your DBCTL information will be on the IMS log instead of the CICS log. IMS uses different log codes to distinguish different types of log record. All user log records in the IMS log have the same code. Records logged using the LOG request will not be backed out if synchronization fails and the UOW is aborted.
The format of the LOG command is:
EXEC DLI LOG FROM(area) LENGTH(expression)
The format of the LOG call is:
CALL 'CBLTDLI' USING LOG ,i/o-pcb,data-area
where LOG is the address of a 4-byte area that contains the value of the LOG function.
The SETS and ROLS requests enable you to define multiple points at which to preserve the state of DL/I full function databases and to return to these points later. The backout points are not CICS syncpoints, they are intermediate backout points that apply only to DBCTL resources. For example, you can use them to allow your program to handle the consequences of PSB scheduling having completed without all of the referenced DL/I databases being available.
The SETS and ROLS requests apply to DL/I full function databases only. If an UOW is updating recoverable resources other than full function databases, for example, DEDBs and VSAM files, the SETS and ROLS requests have no effect on the non-DL/I resources. Therefore, take steps to ensure the consistency of other resources involved, if any. See Summary of DBCTL abends and return codes for explanations of relevant return codes.
You can use a SETS request to define points in your application at which to preserve the state of DL/I databases before initiating a set of DL/I calls to perform a function. Your application can issue a ROLS request later if it cannot complete that function.
The format of the SETS command is:
where mytoken is a 4-byte token associated with the current processing point.
data-area is an area to be restored to the program when a ROLS request is issued. The first two bytes of the data-area field contain the length of the data-area, including the length itself. The second two bytes must be set to X'0000'.
The format of the SETS call is:
TOKEN(mytoken) AREA(data-area) in the command version and i/o_area,token in the call version are optional, but if you do omit them, this cancels any intermediate backout points set in previous SETS requests and ROLS backs out to the last commit point.
You can use the ROLS request to backout to the state all full function databases were in before: (a) a specific SETS request or (b) the most recent commit point.
The format of the ROLS command is:
The format of the ROLS call is:
i/o_area and token on the call, and TOKEN(mytoken) AREA(data-area) on the command are optional. If you include them, ROLS backs out to the SETS you specified. If you omit them, ROLS backs out to the most recent SETS.
The ROLS command has a second format, the purpose of which is to backout to before an ACCEPT STATUSGROUPA request:
where n is the name of a database PCB that has received a "data" unavailable status code. This causes the same action to take place that would have occurred had the program not issued an ACCEPT STATUSGROUPA request. (See Accepting database availability status codes.)
Table 7 lists corresponding EXEC DLI and CALL DL/I requests and their functions.
EXEC DLI | CALL DL/I | Function |
---|---|---|
GU, GN, and GNP | GU, GN, and GNP | Retrieving segments from the database |
GU, GN, and GNP | GHU, GHN, and GHNP | Retrieving segments from database for updating |
DLET | DLET | Deleting segments from a database |
REPL | REPL | Replacing segments in a database |
ISRT | ISRT | Adding segments to a database |
LOAD | ISRT | Initially loading a database |
SCHD | PCB | Scheduling a PSB |
TERM | TERM | Terminating a PSB |
CHKP | CHKP (basic) | Issuing a basic checkpoint |
SYMCHKP | CHKP (extended) | Issuing a symbolic checkpoint |
XRST
RETRIEVE |
XRST | Issuing an extended restart |
-----1 | SYNC | Requesting syncpoint processing |
DEQ | DEQ | Releasing segments retrieved using Q command code |
-----1 | GSCD | Retrieving system addresses |
LOG | LOG | Writing a message to the system log |
ROLL or ROLB | ROLL or ROLB | Dynamically backing out changes |
STAT | STAT | Obtaining system and buffer pool statistics (see also Table 8) |
REFRESH
ACCEPT QUERY2 |
INIT | Refreshing, accepting and querying data availability status codes |
SETS | SETS | Setting a backout point |
ROLS | ROLS | Backing out to a previously set backout point |
-----1 | GSAM | Issuing requests to GSAM databases |
POS | POS | Retrieving positioning and/or space usage information in a DEDB area |
Table 8 summarizes the DL/I requests you can use and the environments in which they apply.
Request type | CICS and DBCTL1 | Batch | BMP |
---|---|---|---|
Get commands and calls (GU, GHU, GN, GHN, GNP, GHNP) | Yes | Yes | Yes |
DLET command and call | Yes | Yes | Yes |
REPL command and call | Yes | Yes | Yes |
ISRT command and call | Yes | Yes | Yes |
ISRT call (initial load) | No | Yes | No |
LOAD command | No | Yes | No |
PCB call | Yes | No | No |
SCHD command | Yes | No | No |
TERM command and call | Yes | No | No |
CHKP command and call (basic) | No | Yes | Yes |
CHKP call (extended) | No | Yes | Yes |
SYMCHKP command | No | Yes | Yes |
XRST command and call | No | Yes | Yes |
RETRIEVE command | No | Yes | Yes |
SYNC call | No | No | Yes |
DEQ command and call | Yes | Yes | Yes |
GSCD call | No | Yes | No |
LOG call | Yes | Yes | Yes |
LOG command | Yes | Yes | Yes |
ROLL call | No | Yes | Yes |
ROLL command | No | Yes | Yes |
ROLB command and call | No | Yes | Yes |
STAT command and call | Yes2 | Yes2 | Yes2 |
INIT call | Yes | Yes | Yes |
REFRESH command | Yes | Yes | Yes |
ACCEPT command | Yes | Yes | Yes |
QUERY command | Yes | Yes | Yes |
SETS command and call | Yes | Yes | Yes |
ROLS command and call | Yes | Yes | Yes |
GSAM calls | No | Yes | Yes |
POS command and call | Yes | No | Yes |