DEDB DL/I calls to extract DEDB information
DL/I calls can be issued to obtain structural information about Data Entry Databases (DEDBs). Any application that can issue DL/I calls can take advantage of these DL/I calls.
There are two basic call types:
- The first type returns the minimum I/O area length required for a specific type '2' DL/I call.
- The second type returns specific information about the specified DEDB.
Each of these DL/I calls uses a call interface block called the Input Output Input Area (IOAI), a telecommunication program PCB (TP PCB), and specific calls that require an I/O area. Some required initialization of the IOAI is common for all calls and some initialization is specific to an individual call. The IOAI and the I/O area must be obtained in key 8 storage.
The following table describes the DL/I calls to extract DEDB information.
| DL/I Call | Description |
|---|---|
| AL_LEN | Returns the minimum length of the I/O area that is required for an AREALIST call. |
| DI_LEN | Returns the minimum length of the I/O area that is required for an DEDBINFO call. |
| DS_LEN | Returns the minimum length of the I/O area required for a DEDBSTR call. |
| AREALIST | Returns a list of areas that are part of the specified DEDB, with each area mapped by DBFCDAL1. |
| DEDBINFO | Returns DEDB information from the DMCB, mapped by DBFCDDI1. |
| DEDBSTR | Returns a list of segments and a segment data for DEDB with each segment mapped by DBFCDDS1. |
The DL/I call that use the standard interface with register 1 must point to IOAI_CA.
The following figure shows the IOAI structure.
starting
offset note
IOAI_START DS 0F
IOAI_NAME DC CL4'IOAI' 0 *1
IOAI_#FPU DC CL4'#FPU' 4 *1
IOAI_#FPI DC CL8'#FPUCDPI' 8 *1
IOAI_SUBC DC CL8' ' 10 *1
*
IOAI_BLEN DC A(0) 18 *1
IOAI_ILEN DC A(0) 1C *1
IOAI_IOAREA DC A(0) 20 *1
*
IOAI_CALL DC A(0) 24 *1
IOAI_PCBI DC A(0) 28 *1
IOAI_IOAI DC A(0) 2C *1
*
IOAI_DLEN DC A(0) 30 *2
IOAI_STATUS DC CL2' ' 34 *2
IOAI_B_LEVEL DC XL2'0' 36 *2
IOAI_STATUS_RC DC A(0) 38 *2
IOAI_USERVER DC A(0) 3C *1
IOAI_IMSVER DC A(0) 40 *2
*
IOAI_IMSLEVEL DC A(0) 44 *2
*
IOAI_APPL_NAME DC CL8' ' 48 *1
IOAI_USERDATA DC CL8' ' 50 *1
IOAI_TIMESTAMP DC CL8' ' 58 *2
* input words.
IOAI_IN0 DC A(0) 60 *3
IOAI_IN1 DC A(0) 64 *3
IOAI_IN2 DC A(0) 68 *3
IOAI_IN3 DC A(0) 6C *3
IOAI_IN4 DC A(0) 70 *3
* feedback words
IOAI_FDBK0 DC A(0) 74 *2
IOAI_FDBK1 DC A(0) 78 *2
IOAI_FDBK2 DC A(0) 7C *2
IOAI_FDBK3 DC A(0) 80 *2
IOAI_FDBK4 DC A(0) 84 *2
* workareas.
IOAI_WA0 DC A(0) 88 *4
IOAI_WA1 DC A(0) 8C *4
IOAI_WA2 DC A(0) 90 *4
IOAI_WA3 DC A(0) 94 *4
IOAI_WA4 DC A(0) 98 *4
*
DS 20F'0' 9C for future expansion
IOAI_END_CHAR DC CL4'IEND' EC *1
IOAI_LEN len(DBFIOAI) = x'F0' bytes Note:
- The user is responsible for initializing these fields.
- IMS uses these fields to return data to the caller. Which fields contain returned data depends on the DL/I call and are documented in the section on the specific call types.
- May be used to pass additional data on the DL/I call, as documented under each DL/I call.
- These fields are unchanged, and can be used as work areas by the application.
The fields in the following table must be initialized for all of the following DL/I calls.
| Field | Description |
|---|---|
| IOAI_NAME | The characters 'IOAI' identifying this block. |
| IOAI_#FPU | The characters '#FPU' Indicating this is a #FPU call. |
| IOAI_#FPI | The characters '#FPUCDPI' indicating this is a subset call. |
| IOAI_SUBC | The DL/I call: AL_LEN, AREALIST, DS_LEN, DEDBSTR, DI_LEN or DEDBINFO. |
| IOAI_BLEN | The total length of the IOAI (x'F0'). |
| IOAI_CALL | Address of IOAI_#FPU. |
| IOAI_PCBI | Address of the TPCB. |
| IOAI_IOAI | Address of this block. The user must set the high order bit on to indicate the end of the DL/I list. |
| IOAI_USERVER | Call version number. Defaults to one. This is the version number of a specific call. This field will be updated in the future if a specific call is altered such that the application must be sensitive to the changes. |
| IOAI_END_CHAR | The chars 'IEND' identifying the end of block. |
The following fields are initialized for specific DL/I calls. If a specific call does not need an I/O area, these fields are ignored.
| Field | Description |
|---|---|
| IOAI_ILEN | The total length of the I/O area, including prefix and suffix. |
| IOAI_IOAREA | Address of the I/O area. |
| I/O Area | 1st word: The I/O area length (same as IOAI_ILEN). Last word: X'FFFFFFFF', which is an 'end of I/O area' marker. |
| IOAI_IN0 -> IOAI_IN4 | Five input words that might be required. |
The following fields are updated by IMS for all the DEDB DL/I call types.
| Field | Description |
|---|---|
| IOAI_DLEN | The length of the output data that is returned by IMS. This field is informational only. |
| IOAI_STATUS | A 2-byte status code. |
| IOAI_STATUS_RC | A return code if needed. |
| IOAI_IMSVER | The maximum version of this call. |
| IOAI_IMSLEVEL | The IMS level. |
The following fields might be updated by specific DL/I calls.
| Field | Description |
|---|---|
| I/O Area | 1st word: unchanged. Data: see specific call types. Last word: potentially changed. |
| IOAI_FDBK0 -> IOAI_FDBK4 | Five output words which may return data as documented by specific calls. |
DBFCDAL1 mapping: offset
CDAL_START DS 0F
CDAL_ARNM DS CL8 00 Area name
CDAL_FLGS DS 0XL4 08 Flag Bytes
CDAL_FLG1 DS XL1 08 Flags for area status:
CDAL_F1OP EQU X'01' - Area is opened
CDAL_F1BK EQU X'02' - Temporary bit for backout
CDAL_F1UT EQU X'04' - Utility active on this area
CDAL_F1ER EQU X'08' - Error recovery needed
CDAL_F1AF EQU X'80' - Sequential dep. part full
CDAL_F1EP EQU X'40' - I/O error
CDAL_F1ST EQU X'20' - Area stop request
CDAL_F1RE EQU X'10' - Area restart request
CDAL_FLG2 DS XL1 09 Reserved for Flag Byte #2
CDAL_FLG3 DS XL1 0A Reserved for Flag Byte #3
CDAL_FLG4 DS XL1 0B Reserved for Flag Byte #4
DS 1F 0C for growth
CDAL_LEND DS 0F End of area list entry
CDAL_LEN EQU *-&AA._START; Len of area list entry DBFCDDI0 mapping: offset
CDDI_START DS 0D
CDDI_DBNM DS CL8 00 Database name
CDDI_ANR DS H 08 Number of areas defined
CDDI_HSLV DS H 0A Max SEGM level in the DB
CDDI_SGNR DS H 0C Highest valid SEGM code
CDDI_SEGL DS H 0E Maximum IOA length
CDDI_HBLK DS F 10 Number of anchor blocks
CDDI_RMNM DS CL8 14 Randomizing module name
CDDI_RMEP DS F 1C Randomizing module entry point
DS 8F 20 Reserved
DS 0D Align on double word boundary
CDDI_LEN EQU *-&AA._START; Length of this area (x'40') DBFCDDS1 mapping: offset
CDDS_START DS 0F
CDDS_GNAM DS CL8 00 SEGMENT NAME
CDDS_GDOF DS H 08 OFFSET FROM START SEQ TO DATA
CDDS_MAX DS H 0A MAX SEG LEN
CDDS_MIN DS H 0C MIN SEG LEN
CDDS_DBOF DS H 0E OFFSET TO SEG ENTRIES
CDDS_NRFLD DS FL1 10 NUMBER OF FIELDS IN SEG
CDDS_SC DS FL1 11 SEGMENT CODE
CDDS_PREF DS H 12 POINTER OFFSET IN PARENT PREF
CDDS_FLG1 DS X 14 FLAG BYTE
CDDS_FL1K EQU X'80' KEY SEGMENT
CDDS_FL1S EQU X'40' SEQUENTIAL DEP SEGMENT
CDDS_FL1P EQU X'20' PCL POINTER TO PARENT
CDDS_FISRT DS X 15 INSERT RULES
CDDS_PARA DS H 16 OFFSET TO PARENT SEGMENT
CDDS_SBLP DS F 18 SIBLING POINTER
CDDS_LEVL DS XL1 1C SEGMENT LEVEL
CDDS_KEYL DS XL1 1D KEY LENGTH - 1
CDDS_KDOF DS H 1E OFFSET TO KEY FIELD IN SEGMENT
CDDS_RSRVE DS XL4 20 FOR USE IN UMDR0 | RESERVED
CDDS_CMPC DS A 24 A(CMPC)
CDDS_FLG2 DS XL1 28 FLAG BYTE 2 (fixed length)
DS XL3 29 FOR GROWTH
DS 5F 2C for growth
CDDS_END DS 0F END
CDDS_LEN EQU *-&AA._START; len of SDB entry The following status codes are specific to these new DL/I calls.
| Status Code | Description |
|---|---|
| AA | Invalid #FPU/#FPUCDPI call. |
| AB | Getmain error. |
| AC | DEDB name not found. |
| AD | The I/O area was not long enough to contain the data. |
| AE | IOAI_LEN was zeros. It must be filled by the caller. |
| AF | The I/O area address was not passed in by IOAI_IOAREA. |
| AG | The IOAI does not point to itself, IOAI_IOAI. |
| AH | The IOAI did not contain 'IOAI'. |
| AI | The I/O area length in the I/O area does not match IOAI. |
| AJ | The I/O area did not contain the end-of-list marker. |
| AK | The IOAI did not have end-of-block marker 'IEND'. |
| AL | IOAI_BLEN is not correct. |
| AM | DEDB not passed in via the IOAI on the #FPUCDPI call. |
| FX | The IOAREA of a POS call has a 4-byte LL field. |