|
Command title |
Insert by Key |
|
Description |
This command inserts a new row into a table. |
|
COBOL syntax |
|
|
Parameters |
xxxx-ROW-AREA xxxx-KEY-AREA — included for backward compatibility. The table key is extracted from xxxx-ROW-AREA, and the xxxx-KEY-AREA parameter is ignored. |
|
Explanation |
The IK command searches the table for a row with a key matching the one specified. If it is not found, then the contents of xxxx-ROW-AREA are inserted into the proper position within the table based upon the results of the search and the table organization. For Random and User ordered tables, the new row is inserted at the end. If the key is found in the table, then the new row is not inserted as the key already exists. |
|
Return value |
If the row is inserted in the table, COUNT contains the subscript for the inserted row and FOUND is set to N. If the row is found, FOUND is set to Y, the row is not inserted in the table and COUNT is set to the subscript of the found row. The table must be open for write in the TSR or VTS-TSR. Multiple error codes can be returned by this command. |
|
Notes |
In a very large Random or User Ordered table, populating an entire table with this command could be quite slow, as this organization forces serial searches and these become slower as the table grows. If key uniqueness checking is not required the IC command is the fastest way to populate a Random table (see Insert by Count (IC)). |
|
Exceptions |
For a single batch program using a local TSR, the table can be open for read. |
|
See also |
- Notices
- Preface
- Introduction
- tableBASE basics
- tableBASE
commands
- Retrieval commands
- Update commands
- Table control commands
- Library maintenance commands
- System control commands
- tableBASE command descriptions
- Allocate (AL)
- Banner Retrieval (BN)
- Create Alternate Index Definition (CA)
- Change Table Definition (CD)
- Change Generations (CG)
- Close Table (CL)
- Change Name (CN)
- Change Status (CS)
- Delete by Count (DC)
- Dump Definition (DD)
- Disengage (DE)
- Delete Generation (DG)
- Delete by Key (DK)
- Define New Library (DL)
- Define Table (DT)
- Dump Table Contents (DU)
- Divert (Non-existing) Table (DV)
- Divert (Existing) Table (DW)
- Fetch by Count (FC)
- Fetch Generic (FG)
- Fetch by Key (FK)
- Fetch Next by Key (FN)
- Get Table Definition (GD)
- Get First (GF)
- Get Last (GL)
- Get Next (GN)
- Get Previous (GP)
- Invoke Alternate Index (IA)
- Insert by Count (IC)
- Insert by Key (IK)
- List Directory (LD)
- List Library (LL)
- List Status (LS)
- List Open Tables (LT)
- List VTS Settings (LV)
- Modify Library Search Order (ML)
- Empty the Table (MT)
- Get Next Table Name (NX)
- Open for Read (OR)
- Open for Write (OW)
- Replace by Count (RC)
- Refresh Table (RF)
- Replace by Key (RK)
- Release Table (RL)
- Rename Table (RN)
- Set Indirect (SI)
- Search by Key (SK)
- Store Table (ST)
- Un-allocate (UL)
- Virtual Subsystem (VS)
- Vary VTS (VV)
- Eliminate Table (XT)
- Terminate tableBASE in Region (XX)
- tableBASE error codes
- tableBASE
parameter description
- ALT-DEFINITION (12 bytes)
- COMMAND-AREA (72 bytes)
- 1. COMMAND (2 bytes)
- 2. TABLE (8 bytes)
- 3. FOUND (1 byte)
- 4. INDIRECT-OPEN (1 byte)
- 5. FILLER (1 byte)
- 6. ABEND-OVERRIDE (1 byte)
- 7. ERROR (halfword binary)
- 8. COUNT (fullword binary)
- 9. LOCK-LATCH (8 bytes)
- 10. ROW-OVERRIDE-LENGTH (fullword binary)
- 11. ROW-ACTUAL-LENGTH (fullword binary)
- 12. FG-KEY-LENGTH (halfword binary)
- 13. FUNCTION-ID (halfword binary)
- 14. FUNCTION-AREA: DATE (8 bytes)
- 15. TB-VSAM-FS-KEY (2 bytes)
- 16. FILLER (17 bytes)
- 17. START-TBUOW (1 byte)
- 18. RETURNED-ABS-GEN-NO (halfword binary)
- 19. ERROR-SUBCODE (halfword binary)
- DATA-TABLE-NAME (8 bytes)
- DDNAME (8 bytes)
- DEFINITION-BLOCK (256 bytes)
- 1. ORG (1 byte)
- 2. METHOD (1 byte)
- 3. INDEX (1 byte)
- 4. SMC (1 byte)
- 5. RPSWD (8 bytes)
- 6. WPSWD (8 bytes)
- 7. RSZ (fullword binary)
- 8. KSZ (fullword binary)
- 9. KLOC (fullword binary)
- 10. ROWS (fullword binary)
- 11. GENERATIONS (halfword binary)
- 12. EXP-FACT (halfword binary)
- 13. LO-DEN (halfword binary)
- 14. HI-DEN (halfword binary)
- 15. FILLER (6 bytes)
- 16. DATE (12 bytes)
- 17. ABS-GEN-NO (halfword binary)
- 18. DATASET-NAME (44 bytes)
- 19. REL-GEN-NO (halfword binary)
- 20. GENS-PRESENT (halfword binary)
- 21. ROWS-AT-EXPAND (fullword binary)
- 22. DDNAME (8 bytes)
- 23. DATA-TABLE (8 bytes)
- 24. OPEN-STATUS (1 byte)
- 25. ALTS-INVOKED (1 byte)
- 26. VIEW-VERSION (1 byte)
- 27. FILLER (1 byte)
- 28. USERID (8 bytes)
- 29. VIEW-NAME (8 bytes)
- 30. VIEW-DATE (12 bytes)
- 31. USER-COMMENTS (16 bytes)
- 32. VTSNAME (8 bytes)
- 33. FILLER (68 bytes)
- DIR-SPEC (9 bytes)
- GENERATION (fullword binary)
- INDIRECT-OPEN-CRITERION (50 bytes)
- KEY-AREA (Table Specific)
- LIB-LIST (80 bytes)
- LIB-SPACE (8 bytes)
- LIBMETA-DATA (20 bytes)
- LIBRARY-ALLOC (45 bytes)
- LIST-BLOCK (88 bytes)
- 1. LIST-FROM (fullword binary)
- 2. LIST-REQD (fullword binary)
- 3. LIST-SIZE (fullword binary)
- 4. LIST-TOTAL (fullword binary)
- 5. LIST-RETURNED (fullword binary)
- 6. LIST-TSR-HW (fullword binary)
- 7. LIST-OPEN-HW (fullword binary)
- 8. LIST-OPEN-NOW (fullword binary)
- 9. LIST-TSR-NOW (fullword binary)
- 10. LIST-TSR-SZ (fullword binary)
- 11. LIST-STROBE (fullword binary)
- 12. LIST-TOTAL-HWM (fullword binary)
- 13. LIST-TOTAL-CALLS (doubleword binary)
- 14. LIST-MAX-TBLS (fullword binary)
- 15. FILLER (16 bytes)
- 16. LIST-TSR-AVAIL (fullword binary)
- 17. FILLER (8 bytes)
- NAME-AREA (256 bytes)
- NEW-GEN-NO (fullword binary)
- NEW-TABLE-NAME (8 bytes)
- PASSWORD (8 bytes)
- RELEASE-LEVEL (16 bytes)
- ROW-AREA (Table Specific)
- STATUS-SWITCHES (8 bytes)
- TABLE-AREA
- TABLE-STATS
- 1. TABLE-NAME (8 bytes)
- 2. TABLE-OPEN-STATUS (1 byte)
- 3. TABLE-LOCAL-VTS (1 byte)
- 4. TABLE-ALT-INVOKED (1 byte)
- 5. FILLER (1 byte)
- 6. TABLE-CALLS (fullword binary)
- 7. TABLE-SIZE (fullword binary)
- 8. TABLE-ROWS (fullword binary)
- 9. TABLE-RWS-BF-EXP (fullword binary)
- 10. TABLE-DATATBL-VTSNAME (8 bytes)
- 11. TABLE-UPDATE-CALLS-TRUNC (fullword binary)
- 12. TABLE-DATE-TIME (12 bytes)
- 13. FILLER (4 bytes)
- 14. TABLE-TOTAL-CALLS (doubleword binary)
- 15. TABLE-UPDATE-CALLS (doubleword binary)
- 16. TABLE-VTSNAME (8 bytes)
- TBACC-DEF (32 bytes)
- TBINDEX-DEF (32 bytes)
- TB-PARM V5 (64 bytes)
- TB-PARM V4 (28 bytes)
- VTS-DATA (60 bytes)
- 1. FILLER (8 bytes)
- 2. VTS-VTSFIRST (8 bytes)
- 3. VTS-VTSLAST (8 bytes)
- 4. VTS-VTSNAME (8 bytes)
- 5. VTS-DEFAULT-TSR (8 bytes)
- 6. VTS-TSRACCESS (1 byte)
- 7. VTS-RACF-VTS (1 byte)
- 8. VTS-TSR-KEY-PROTECT (1 byte)
- 9. FILLER (3 bytes)
- 10. VTS-GENERATION (2 bytes)
- 11. VTS-TPVM (8 bytes)
- 12. VTS-PREFIX (4 bytes)
- VTS-NAME (8 bytes)
- tableBASE parameters with C
- tableBASE coding examples
- Summary of coding examples
- Coding conventions
- Programming in C with tableBASE
- Retrieval commands
- Update commands
- Table control commands
- Library maintenance commands
- System control commands
- Sample tableBASE applications
- Fetch a row from a table
- Update an existing table
- Sequentially process all rows in a table
- Generic search
- Define a dynamic table to summarize data in memory
- Access a table that may not exist
- Establish another key with which to search a table
- Concatenate tableBASE libraries
- Temporarily change a list of concatenated tableBASE libraries
- Access a table indirectly
- Other language examples
- Environmental interfaces
- Customizing tableBASE options
- tableBASE driver command processor for CICS
- DK1TDRV command processor for Batch/TSO
- Error diagnosis
- tableBASE subroutines
- tablesONLINE/ISPF exit programming
- tablesONLINE/CICS exit programming
- Interacting with tablesONLINE/CICS
- Top-level control structure for an exit
- Before Action exits
- After Action exits
- tablesONLINE/CICS system exits
- Command Line/Line Command processing exits
- BYPASS-ACTION-IND summary
- Constructing an exit program
- The EXITWS copybook
- The EXITPARM copybook
- Exit program scenarios
- tableBASE Runtime Options
- ALLOW_TB_LIB_IO—Allow tableBASE Library I/O
- CICSJRNL—CICS Journal File ID
- DATERTNX—Date-Sensitive Processing Found Code
- FGDELIM—Fetch Generic Delimiter
- HASH_HI_DEN_LIM—High Density Limit for Hash Indexes
- HASH_LOW_DEN_LIM—Low Density Limit for Hash Indexes
- LDS—Linear Data Set Use
- LIBnn, ML—tableBASE Library List
- LISTOPTIONS—List Parameter Options
- LOCKTIMERC—Lock Timer Wait Value
- LOCKTIMEWTO—Lock Timer Message Wait Value
- LOCKTIMEREADOVRD – Lock Timer Read Override
- MAXNMTAB—Maximum Number of Tables
- MTRETAIN—Retain Rows and Index Areas
- MULTITASKING—Multitasking
- MULTOPNX—Multiple Alternate Index
- OVRRIDES—Allow Changes to Status Switches
- RACF_LIBACCESS—Perform Checks on Protected Libraries
- RACF_VTS—Perform Checks on SAF Interface Protected VTS-TSRs
- STROBE—Strobe Interval
- STROBEMETHOD—Strobe Method
- SUPPRESS_DUMPS—Suppress tableBASE Messages and Dumps
- SWITCHES—Status Switches
- TABLEWAITRC—Table Open Enqueue Wait Time
- TABLEWAITWTO—Table Open Enqueue Report Time
- TSR_ALGORITHM—Optimize TSR Usage
- TSR_KEY_PROTECT—Hardware Key Protection for VTS-TSRs
- TSR_WARNING_FREQ—Frequency of TSR Allocation Warnings
- TSR_WARNING_PCT—Percentage of TSR Allocation for Warning Activation
- TSRACCESS—Read Only (RO), Refreshable (RF), and Read Write (RW) TSR Access
- TSRSIZE—tableSPACE Region Size
- USEREXITS—User Exits
- VTSFIRST, VTSLAST—VTS Search Sequence
- VTSNAME—Specifying the Name of a VTS-TSR
- VTSPREFIX—VTS Prefix Definition
- ZEROROWS—Zero Data Table Rows on De-allocation
- TBOPT dataset coding
- Hints and suggestions
- tableBASE space requirements
- FK for duplicate keys
- Optimizing table access
- High-speed processing without EDF
- Date-sensitive processing
- Access Register mode
- VSAM tableBASE libraries and LSR pools
- Considerations for working with large tables
- tableBASE libraries
- Linked tables and TB-PARM
- Performance and TB-PARM
- Application performance with TBASEV or TBCALLV
- Limitations of duplicate key support
- Compatibility with previous releases of tableBASE
- tableBASE messages
- Sample tableBASE COBOL call template
- Home
- /
- Documentation Archive
- /
- V 7.0.3 tableBASE Programming Guide
- /
- tableBASE commands
- /
- tableBASE command descriptions