@linkup-ai/abap-ai 2.0.0

package/dist/knowledge/abap/exceptions.md

@@ -0,0 +1,271 @@
+# Exceptions — class-based, message class, RAP reporting
+
+## Exception Hierarchy
+
+```
+CX_ROOT (abstract)
+├── CX_STATIC_CHECK    — caller MUST handle (compile-time check)
+├── CX_DYNAMIC_CHECK   — caller SHOULD handle (runtime check)
+└── CX_NO_CHECK        — programming errors (should not catch)
+```
+
+## Defining Exception Class
+
+```abap
+CLASS zcx_order_error DEFINITION
+  INHERITING FROM cx_static_check
+  PUBLIC FINAL CREATE PUBLIC.
+
+  PUBLIC SECTION.
+    INTERFACES if_t100_message.
+    INTERFACES if_t100_dyn_msg.
+
+    CONSTANTS:
+      BEGIN OF customer_not_found,
+        msgid TYPE symsgid VALUE 'ZORDER',
+        msgno TYPE symsgno VALUE '001',
+        attr1 TYPE scx_attrname VALUE 'MV_CUSTOMER_ID',
+        attr2 TYPE scx_attrname VALUE '',
+        attr3 TYPE scx_attrname VALUE '',
+        attr4 TYPE scx_attrname VALUE '',
+      END OF customer_not_found,
+      BEGIN OF invalid_amount,
+        msgid TYPE symsgid VALUE 'ZORDER',
+        msgno TYPE symsgno VALUE '002',
+        attr1 TYPE scx_attrname VALUE 'MV_AMOUNT',
+        attr2 TYPE scx_attrname VALUE '',
+        attr3 TYPE scx_attrname VALUE '',
+        attr4 TYPE scx_attrname VALUE '',
+      END OF invalid_amount.
+
+    DATA mv_customer_id TYPE kunnr READ-ONLY.
+    DATA mv_amount TYPE netwr READ-ONLY.
+
+    METHODS constructor
+      IMPORTING textid      LIKE if_t100_message=>t100key OPTIONAL
+                previous    LIKE previous OPTIONAL
+                mv_customer_id TYPE kunnr OPTIONAL
+                mv_amount   TYPE netwr OPTIONAL.
+ENDCLASS.
+
+CLASS zcx_order_error IMPLEMENTATION.
+  METHOD constructor.
+    super->constructor( previous = previous ).
+    me->mv_customer_id = mv_customer_id.
+    me->mv_amount = mv_amount.
+    CLEAR me->textid.
+    IF textid IS INITIAL.
+      if_t100_message~t100key = if_t100_message=>default_textid.
+    ELSE.
+      if_t100_message~t100key = textid.
+    ENDIF.
+  ENDMETHOD.
+ENDCLASS.
+```
+
+## Raising Exceptions
+
+```abap
+" With text ID (message class)
+RAISE EXCEPTION TYPE zcx_order_error
+  EXPORTING textid = zcx_order_error=>customer_not_found
+            mv_customer_id = lv_customer.
+
+" With previous (chained)
+TRY.
+    lo_service->process( ).
+  CATCH cx_static_check INTO DATA(lx_prev).
+    RAISE EXCEPTION TYPE zcx_order_error
+      EXPORTING textid   = zcx_order_error=>invalid_amount
+                previous = lx_prev
+                mv_amount = lv_amount.
+ENDTRY.
+
+" Quick message (without custom exception class)
+RAISE EXCEPTION TYPE cx_abap_message_digest
+  EXPORTING text = |Customer { lv_id } not found|.
+```
+
+## Catching Exceptions
+
+```abap
+TRY.
+    lo_processor->execute( iv_data = lv_input ).
+  CATCH zcx_order_error INTO DATA(lx_order).
+    DATA(lv_msg) = lx_order->get_text( ).
+    DATA(lv_long) = lx_order->get_longtext( ).
+  CATCH cx_static_check INTO DATA(lx_generic).
+    " Fallback for any checked exception
+ENDTRY.
+
+" Multiple CATCH
+TRY.
+    process( ).
+  CATCH zcx_order_error INTO DATA(lx1).
+    " Handle order errors
+  CATCH zcx_auth_error INTO DATA(lx2).
+    " Handle auth errors
+  CATCH cx_static_check INTO DATA(lx3).
+    " Handle all other checked exceptions
+ENDTRY.
+
+" RETRY
+TRY.
+    lo_api->call( ).
+  CATCH cx_sy_remote_call_error.
+    IF lv_retries < 3.
+      lv_retries += 1.
+      RETRY.
+    ENDIF.
+ENDTRY.
+
+" CLEANUP (runs before leaving TRY block on exception)
+TRY.
+    lo_file->open( ).
+    lo_file->write( ).
+  CLEANUP.
+    lo_file->close( ).
+ENDTRY.
+```
+
+## Message Class (SE91)
+
+```abap
+" Message class ZORDER:
+" 001: Customer &1 not found
+" 002: Amount &1 is invalid
+" 003: Order &1 created successfully
+
+" Using in code
+MESSAGE e001(zorder) WITH lv_customer INTO DATA(lv_msg).
+
+" Accessing SY-MSG* after MESSAGE ... INTO
+" sy-msgid = 'ZORDER'
+" sy-msgno = '001'
+" sy-msgty = 'E'
+" sy-msgv1 = lv_customer
+```
+
+## RAP — Error Reporting in Validations
+
+```abap
+METHOD validate_customer.
+  READ ENTITIES OF ZI_Order IN LOCAL MODE
+    ENTITY Order FIELDS ( CustomerID )
+    WITH CORRESPONDING #( keys )
+    RESULT DATA(orders).
+
+  LOOP AT orders INTO DATA(order).
+    APPEND VALUE #( %tky = order-%tky ) TO result.
+
+    IF order-CustomerID IS INITIAL.
+      " Using message class
+      APPEND VALUE #(
+        %tky        = order-%tky
+        %state_area = 'VALIDATE_CUSTOMER'
+        %msg        = NEW zcm_order(
+                        textid      = zcm_order=>customer_required
+                        severity    = if_abap_behv_message=>severity-error )
+        %element-CustomerID = if_abap_behv=>mk-on
+      ) TO reported-order.
+
+      APPEND VALUE #( %tky = order-%tky ) TO failed-order.
+    ENDIF.
+  ENDLOOP.
+ENDMETHOD.
+```
+
+## RAP — Message Class for RAP (zcm_*)
+
+```abap
+" Convention: ZCM_<bo_name> inheriting from CX_STATIC_CHECK
+CLASS zcm_order DEFINITION
+  INHERITING FROM cx_static_check
+  PUBLIC FINAL CREATE PUBLIC.
+
+  PUBLIC SECTION.
+    INTERFACES if_abap_behv_message.
+    INTERFACES if_t100_message.
+    INTERFACES if_t100_dyn_msg.
+
+    CONSTANTS:
+      BEGIN OF customer_required,
+        msgid TYPE symsgid VALUE 'ZORDER',
+        msgno TYPE symsgno VALUE '010',
+        attr1 TYPE scx_attrname VALUE '',
+        attr2 TYPE scx_attrname VALUE '',
+        attr3 TYPE scx_attrname VALUE '',
+        attr4 TYPE scx_attrname VALUE '',
+      END OF customer_required.
+
+    METHODS constructor
+      IMPORTING severity TYPE if_abap_behv_message=>t_severity DEFAULT if_abap_behv_message=>severity-error
+                textid   LIKE if_t100_message=>t100key OPTIONAL
+                previous LIKE previous OPTIONAL.
+ENDCLASS.
+
+CLASS zcm_order IMPLEMENTATION.
+  METHOD constructor.
+    super->constructor( previous = previous ).
+    if_abap_behv_message~m_severity = severity.
+    CLEAR me->textid.
+    IF textid IS INITIAL.
+      if_t100_message~t100key = if_t100_message=>default_textid.
+    ELSE.
+      if_t100_message~t100key = textid.
+    ENDIF.
+  ENDMETHOD.
+ENDCLASS.
+```
+
+## Quick Messages in RAP (without custom message class)
+
+```abap
+" new_message_with_text — simple, no message class needed
+APPEND VALUE #(
+  %tky = order-%tky
+  %msg = new_message_with_text(
+    severity = if_abap_behv_message=>severity-error
+    text     = |Customer { order-CustomerID } is invalid| )
+  %element-CustomerID = if_abap_behv=>mk-on
+) TO reported-order.
+
+" new_message — using message class directly
+APPEND VALUE #(
+  %tky = order-%tky
+  %msg = new_message(
+    id       = 'ZORDER'
+    number   = '001'
+    severity = if_abap_behv_message=>severity-error
+    v1       = order-CustomerID )
+) TO reported-order.
+```
+
+## Severity Levels
+
+| Constant | Value | Fiori Display |
+|----------|:-----:|---------------|
+| `if_abap_behv_message=>severity-error` | 'E' | Red, blocks save |
+| `if_abap_behv_message=>severity-warning` | 'W' | Yellow, allows save |
+| `if_abap_behv_message=>severity-information` | 'I' | Blue, informational |
+| `if_abap_behv_message=>severity-success` | 'S' | Green, success |
+
+## Rules
+- Use `cx_static_check` for expected business errors (caller must handle)
+- Use `cx_no_check` only for programming bugs (null reference, division by zero)
+- RAP validations: NEVER raise exceptions — always use `reported` + `failed`
+- RAP: use `%state_area` to group related messages (field group in Fiori)
+- RAP: use `%element-FieldName = if_abap_behv=>mk-on` to highlight field in UI
+- Prefer message class (SE91) over hardcoded text for i18n support
+- Convention: `zcx_*` for general exceptions, `zcm_*` for RAP behavior messages
+
+## Anti-Patterns
+| Anti-Pattern | Correct |
+|---|---|
+| `CATCH cx_root` everywhere | Catch specific exception types |
+| Empty CATCH block | At minimum log or re-raise |
+| `RAISE EXCEPTION` in RAP validation | Use `reported` + `failed` |
+| Hardcoded text in `new_message_with_text` for production | Use message class for i18n |
+| `cx_static_check` for programming errors | Use `cx_no_check` |
+| Missing `%element` in RAP reported | Field not highlighted in Fiori UI |
+| Missing `%state_area` in RAP reported | Messages not grouped properly |

package/dist/knowledge/abap/internal-tables.md

@@ -0,0 +1,205 @@
+# Internal Tables — declaration, access, iteration, performance
+
+## Table Types
+
+```abap
+" Standard — index + key, non-unique, sequential processing
+DATA zt_items TYPE STANDARD TABLE OF zs_item WITH EMPTY KEY.
+
+" Sorted — index + key, binary search O(log n)
+DATA zt_sorted TYPE SORTED TABLE OF zs_item WITH UNIQUE KEY id.
+DATA zt_nonuniq TYPE SORTED TABLE OF zs_item WITH NON-UNIQUE KEY category.
+
+" Hashed — key only, O(1) lookup, unique key required
+DATA zt_hashed TYPE HASHED TABLE OF zs_item WITH UNIQUE KEY id.
+```
+
+## Declaration Patterns
+
+```abap
+" Inline with VALUE
+DATA(zt_names) = VALUE string_table( ( `Alpha` ) ( `Beta` ) ( `Gamma` ) ).
+
+" Structured line type
+DATA(zt_data) = VALUE zt_item_tab(
+  ( id = 1 name = `First` )
+  ( id = 2 name = `Second` ) ).
+
+" Secondary keys
+DATA zt_multi TYPE TABLE OF zs_item
+  WITH EMPTY KEY
+  WITH NON-UNIQUE SORTED KEY by_name COMPONENTS name
+  WITH UNIQUE HASHED KEY by_id COMPONENTS id.
+```
+
+## Populating Tables
+
+```abap
+" VALUE with BASE (append)
+zt_data = VALUE #( BASE zt_data ( id = 3 name = `Third` ) ).
+
+" LINES OF (merge)
+zt_data = VALUE #( BASE zt_data ( LINES OF zt_other ) ).
+
+" FOR iteration
+DATA(zt_gen) = VALUE zt_item_tab(
+  FOR i = 1 UNTIL i > 10
+  ( id = i name = |Entry { i }| ) ).
+
+" FOR from source with WHERE
+DATA(zt_active) = VALUE zt_item_tab(
+  FOR wa IN zt_source WHERE ( status = 'A' )
+  ( wa ) ).
+
+" APPEND with field-symbol
+APPEND INITIAL LINE TO zt_data ASSIGNING FIELD-SYMBOL(<zs_new>).
+<zs_new>-id = 99.
+```
+
+## Reading Entries
+
+```abap
+" Table expression — preferred
+DATA(zs_line) = zt_data[ id = 1 ].
+DATA(lv_name) = zt_data[ 1 ]-name.
+
+" Safe access — OPTIONAL returns initial if not found
+DATA(zs_safe) = VALUE #( zt_data[ id = 999 ] OPTIONAL ).
+
+" Safe access — DEFAULT
+DATA(zs_def) = VALUE #( zt_data[ id = 999 ] DEFAULT VALUE #( id = 0 ) ).
+
+" Existence check
+IF line_exists( zt_data[ id = 1 ] ).
+ENDIF.
+
+" Index lookup
+DATA(lv_idx) = line_index( zt_data[ name = `First` ] ).
+
+" Secondary key access
+DATA(zs_by_name) = zt_multi[ KEY by_name name = `Alpha` ].
+
+" READ TABLE with field-symbol (for modification)
+READ TABLE zt_data ASSIGNING FIELD-SYMBOL(<zs_fs>) WITH KEY id = 1.
+IF sy-subrc = 0.
+  <zs_fs>-name = `Updated`.
+ENDIF.
+```
+
+## Modifying Entries
+
+```abap
+" Direct via table expression
+zt_data[ 1 ]-name = `Changed`.
+
+" Via field-symbol in LOOP
+LOOP AT zt_data ASSIGNING FIELD-SYMBOL(<zs_line>).
+  <zs_line>-name = to_upper( <zs_line>-name ).
+ENDLOOP.
+
+" MODIFY with WHERE
+MODIFY zt_data FROM VALUE #( status = 'X' )
+  TRANSPORTING status WHERE category = 'A'.
+```
+
+## Deleting Entries
+
+```abap
+DELETE zt_data WHERE status = 'D'.
+DELETE TABLE zt_data WITH TABLE KEY id = 1.
+DELETE ADJACENT DUPLICATES FROM zt_data COMPARING name.
+FREE zt_data.  " Clear + release memory
+```
+
+## Iteration
+
+```abap
+" LOOP with field-symbol — preferred
+LOOP AT zt_data ASSIGNING FIELD-SYMBOL(<zs_row>) WHERE status = 'A'.
+ENDLOOP.
+
+" LOOP with data reference
+LOOP AT zt_data REFERENCE INTO DATA(zr_row).
+  zr_row->*-counter += 1.
+ENDLOOP.
+
+" LOOP using secondary key
+LOOP AT zt_multi USING KEY by_name ASSIGNING FIELD-SYMBOL(<zs_named>)
+  WHERE name CS `test`.
+ENDLOOP.
+
+" Group processing
+LOOP AT zt_data INTO DATA(zs_rep) GROUP BY ( cat = zs_rep-category
+                                               size = GROUP SIZE )
+                                    ASSIGNING FIELD-SYMBOL(<zg_grp>).
+  LOOP AT GROUP <zg_grp> ASSIGNING FIELD-SYMBOL(<zs_member>).
+  ENDLOOP.
+ENDLOOP.
+```
+
+## FILTER Expression
+
+```abap
+" Basic filter (requires sorted/hashed key)
+DATA(zt_active) = FILTER #( zt_multi USING KEY by_name WHERE name = `Alpha` ).
+
+" EXCEPT — exclude matching
+DATA(zt_rest) = FILTER #( zt_multi EXCEPT WHERE status = 'A' ).
+
+" Filter with IN (filter table)
+DATA zt_fvals TYPE SORTED TABLE OF string WITH UNIQUE KEY table_line.
+zt_fvals = VALUE #( ( `A` ) ( `B` ) ).
+DATA(zt_matched) = FILTER #( zt_data IN zt_fvals WHERE status = table_line ).
+```
+
+## REDUCE Aggregation
+
+```abap
+DATA(lv_sum) = REDUCE i( INIT s = 0
+  FOR wa IN zt_data
+  NEXT s = s + wa-amount ).
+
+DATA(lv_max) = REDUCE i( INIT m = 0
+  FOR wa IN zt_data
+  NEXT m = COND #( WHEN wa-value > m THEN wa-value ELSE m ) ).
+
+DATA(lv_csv) = REDUCE string( INIT str = ``
+  FOR wa IN zt_data
+  NEXT str = str && wa-name && `, ` ).
+```
+
+## Sorting
+
+```abap
+SORT zt_data BY category ASCENDING amount DESCENDING.
+SORT zt_data BY name AS TEXT STABLE.
+```
+
+---
+
+## Rules
+
+- Use SORTED TABLE for frequent key lookups on medium tables
+- Use HASHED TABLE for large tables with unique key access
+- Always use FIELD-SYMBOL in LOOP when modifying rows
+- Use table expressions `itab[ key = val ]` over READ TABLE for reads
+- Use OPTIONAL or DEFAULT for safe access — avoids CX_SY_ITAB_LINE_NOT_FOUND
+- Use secondary keys instead of repeated SORT for multiple access patterns
+- Use FILTER with USING KEY for efficient subset extraction
+- Check `IS NOT INITIAL` before FOR ALL ENTRIES (same principle applies)
+- Prefer `FREE itab` over `CLEAR itab` when memory should be released
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Approach |
+|---|---|
+| `READ TABLE ... INTO wa` then modify wa (copy, not reference) | `READ TABLE ... ASSIGNING FIELD-SYMBOL(<fs>)` |
+| `LOOP AT itab INTO wa` for modification | `LOOP AT itab ASSIGNING FIELD-SYMBOL(<fs>)` |
+| `READ TABLE itab ... BINARY SEARCH` on unsorted standard table | Use SORTED TABLE or SORT before BINARY SEARCH |
+| `LOOP AT + IF` to filter | `LOOP AT ... WHERE` or FILTER expression |
+| `DESCRIBE TABLE itab LINES lv_count` | `lines( itab )` |
+| `READ TABLE ... sy-subrc` just to check existence | `line_exists( itab[ ... ] )` |
+| Nested LOOP AT for lookup (O(n*m)) | Use HASHED TABLE or secondary key for inner lookup |
+| `DELETE ADJACENT DUPLICATES` without prior SORT | Always SORT first or use SORTED TABLE |
+| `SELECT ... ENDSELECT` appending one by one | `SELECT ... INTO TABLE` |
+| Using DEFAULT KEY on typed tables | Use EMPTY KEY or explicit key fields |