הפניה לניתוח של קובץ Copybook

הכלי Mainframe Connector משתמש במנתח מבוסס-ANTLR4 שתומך ב-copybooks סטנדרטיים של COBOL.

במסמך הזה מפורטות משימות העיבוד המקדים שמבצע מנתח ה-copybook, סוגי הנתונים הנתמכים והגבלות השימוש, ואיך להגדיר משתני שדה באמצעות הגדרת הטרנסקודר עם הפקודות qsam decode ו-qsam encode.

עיבוד מקדים

לפני ניתוח של קובץ copybook, המנתח מבצע עיבוד מקדים של הנתונים ומבצע את השלבים הבאים:

  • הסרת שורות של הערות (* בעמודה 7, או הערות *> ו-*>CE מוטבעות).
  • פותר את המשך השורה (- בעמודה 7 ואחריו ליטרל במירכאות).
  • מרוקן את האזורים של המספרים הסידוריים (עמודות 1-6) ואת עמודה 73 והלאה. הקוד חייב להתחיל בעמודה 8 או בעמודה מאוחרת יותר.
  • שומר הצהרות ספציפיות למעבד מקדים כמו EJECT,‏ SKIP1,‏ SKIP2,‏ SKIP3 ו-TITLE. ההצהרות האלה מנותחות, אבל המערכת מתעלמת מהן. מנתח ה-copybook לא תומך בקובצי copybook שמכילים פרמטרים של מעבד מקדים ש-COPY REPLACING יכול להשתמש בהם. ב-copybooks האלה, המזהים מוקפים בנקודתיים (:).

סוגי נתונים נתמכים והגבלות

אלה סוגי הנתונים שנתמכים על ידי מנתח ה-copybook וההגבלות על השימוש בהם:

  • ב-copybook מותרת רק רשומה אחת ברמה העליונה של 01, ולרשומה 01 לא יכול להיות סעיף OCCURS.
  • אין תמיכה בשדות ברמה 66 (RENAMES / alias) וברמה 77 (standalone). רמה 88 (שמות התנאים) מנותחת והמערכת מתעלמת ממנה.
  • כל השדות הבסיסיים (שאינם קבוצתיים) חייבים לכלול פסוקית PICTURE, למעט שדות של נקודה צפה (floating-point) בבסיס הקסדצימלי (COMP-1 ו-COMP-2). יש תמיכה בשדות PICTURE הבאים:
    • אלפביתי (PIC A), אלפאנומרי (PIC X) ואלפאנומרי ערוך (A, X, 9, B, 0, /).
    • ‫PIC G (DBCS; נדרש USAGE DISPLAY-1).
    • ‫PIC N (לאומי או DBCS) ולאומי-ערוך (N, B, 0, /).
    • PIC U (UTF-8), כולל PIC U BYTE-LENGTH n.
    • מספרי (9, S, V) ומספרי-ערוך ($, B, /, V, Z, 0, 9, ,, ., *, +, -, CR, DB). שימו לב שאין תמיכה ב-PIC P (מיקום קנה מידה).
    • שדות של מספרים עשרוניים ארוזים ומספרים עשרוניים מיושרים עם דיוק של עד 18 מפוענחים לסוגים של 64 ביט (LONG או DECIMAL64), ושדות עם דיוק גבוה יותר מפוענחים לסוגים עם דיוק שרירותי (BIG_INTEGER או BIG_DECIMAL). כשמגדירים את schema_validation_mode לערך BIG_QUERY, הדיוק המקסימלי שנתמך הוא 76 (BIGNUMERIC) והקנה מידה המקסימלי הוא 38 (ב-POSTGRES הדיוק המקסימלי הוא 147,455 והקנה מידה המקסימלי הוא 16,383, וב-MYSQL הדיוק המקסימלי הוא 65 והקנה מידה המקסימלי הוא 30).
  • יש תמיכה ב-IBM Hexadecimal Floating-Point‏ (HFP) באמצעות COMP-1 / COMPUTATIONAL-1 (דיוק יחיד, 4 בייטים) ו-COMP-2 / COMPUTATIONAL-2 (דיוק כפול, 8 בייטים), או באמצעות החלת משנה השדה hfp בהגדרות של הטרנסקודר.
  • אפשר להשתמש בסעיפי REDEFINES בשדות בגודל סטטי, כשכל הווריאציות שהוגדרו מחדש הן באותו גודל בייטים. אי אפשר להפנות לשדות שהוגדרו מחדש כשדה האורך של משפט OCCURS DEPENDING ON או כ-target_field של משנה null_if.
  • סעיפי OCCURS נתמכים במערכים באורך קבוע (OCCURS n TIMES), במערכים באורך דינמי (OCCURS min TO max TIMES DEPENDING ON field) ובמערכים דחוסים באורך דינמי (OCCURS UNBOUNDED DEPENDING ON field). הביטויים ASCENDING/DESCENDING KEY ו-INDEXED BY בסעיף OCCURS לא נתמכים, ו-DEPENDING ON צריך להפנות לשם שדה בהיקף.
  • יש תמיכה רק בסעיפי USAGE הבאים:
    • ‫DISPLAY (ברירת המחדל לשדות אלפאנומריים ולשדות עשרוניים עם סימן)
    • DISPLAY-1 (DBCS)
    • NATIONAL (ברירת המחדל לשדות PIC N, מקודד בתור UTF-16BE)
    • ‫UTF-8 (ברירת המחדל לשדות PIC U)
    • BINARY, COMP, COMPUTATIONAL, COMP-4, COMPUTATIONAL-4, COMP-5, COMPUTATIONAL-5
    • COMP-3, COMPUTATIONAL-3, PACKED-DECIMAL
    • COMP-1,‏ COMPUTATIONAL-1,‏ COMP-2,‏ COMPUTATIONAL-2
  • אפשר להשתמש ב-DATE וב-TIMESTAMP באמצעות הגדרת הטרנסקודר.
  • אפשר להשתמש באינדיקטורים של ערכי null באמצעות הגדרת המקודד.
  • יש תמיכה בשדות PIC G ו-PIC N של ערכת תווים בבייט כפול (DBCS). כברירת מחדל, שדות PIC N ללא פסוקית USAGE מוקצים ל-USAGE NATIONAL (UTF-16BE). כדי להשתמש בשדה PIC N כ-DBCS, צריך לציין את USAGE DISPLAY-1 ב-copybook או לשנות את קידוד התווים שלו בהגדרות של הטרנסקודר.
  • אפשר להשתמש במחרוזות תווים באורך משתנה באמצעות הגדרת המקודד.
  • יש תמיכה בסעיף SIGN (LEADING,‏ TRAILING,‏ SEPARATE CHARACTER).
  • יש תמיכה בתגובות.

תמיכה בשדות של תאריך וחותמת זמן

‫Mainframe Connector תומך בפענוח ובקידוד של שדות תאריך וחותמת זמן באמצעות משני השדות format_date ו-format_timestamp בהגדרות של transcoder ‏(--transcode-configuration). אתם יכולים להחיל את משני השדות האלה על שדות תואמים באמצעות field_suffixes או על שדות ספציפיים באמצעות field_overrides:

{
  "field_suffixes": [
    {
      "suffix": "SUFFIX_STRING",
      "modifier": {
        "format_date": {
          "formats": [
            {
              "size": FIELD_SIZE,
              "pattern": "FORMAT_PATTERN"
            }
          ]
        }
      }
    }
  ]
}

ברשימה הבאה מפורטים מאפייני ההגדרות:

  • ‫suffix: התאמה לכל שדה של קובץ copybook שהשם שלו מסתיים ב--SUFFIX_STRING או ב-_SUFFIX_STRING (ללא תלות באותיות רישיות). חשוב לוודא שהערך של suffix לא מתחיל במקף או בקו תחתון. לחלופין, אפשר להשתמש ב-field_overrides עם "field": "FIELD_NAME" כדי לטרגט שדה ספציפי.
  • format_date / format_timestamp: מגדיר את המשתנה שמשמש לניתוח או לעיצוב השדה:
    • אפשר להחיל את format_date על שדות של מחרוזות בגודל מסוים (PIC X) או על שדות מספריים של מספרים שלמים (כמו PIC 9(n),‏ COMP או COMP-3 עם קנה מידה 0 ודיוק של עד 18, שמומרים באופן דינמי לייצוג המחרוזת ללא סימן לפני העיצוב).
    • אפשר להחיל את format_timestamp על שדות של מחרוזות בגודל מסוים (PIC X). חותמות הזמן מפורשות לפי שעון UTC, אלא אם התבנית כוללת אזור זמן או סטייה.
  • ‫formats: רשימה של אובייקטים מסוג DateTimeFormat, שכל אחד מהם מציין:
    • size: גודל השדה שהתבנית חלה עליו (אורך בייטים לשדות של מחרוזות, או דיוק לשדות מספריים).
    • ‫pattern: תבנית של תאריך או חותמת זמן. במהלך הפענוח (qsam decode), הפורמטים שתואמים לגודל השדה נבדקים לפי הסדר עד שנמצאת התאמה. במהלך הקידוד (qsam encode), המערכת משתמשת רק בפורמט הראשון שתואם לגודל השדה. מידע נוסף על פורמטים תקינים זמין במאמר פורמטים נתמכים של תאריכים וחותמות זמן.
  • הסרת סיומות (אופציונלי): כדי להסיר את -SUFFIX_STRING או את _SUFFIX_STRING משם שדה הפלט, מוסיפים טרנספורמציה של rename למערך transformations בהגדרת הטרנסקודר.

דוגמאות

  • כדי לעצב שדות של 8 בייטים שמסתיימים ב--DT8 או ב-_DT8 בתור DATE עם התבנית yyyyMMdd, ושדות של 10 בייטים שמסתיימים ב--DT או ב-_DT עם MM-dd-yyyy או MM/dd/yyyy:

    {
      "field_suffixes": [
        {
          "suffix": "DT8",
          "modifier": {
            "format_date": {
              "formats": [
                {
                  "size": 8,
                  "pattern": "yyyyMMdd"
                }
              ]
            }
          }
        },
        {
          "suffix": "DT",
          "modifier": {
            "format_date": {
              "formats": [
                {
                  "size": 10,
                  "pattern": "MM-dd-yyyy"
                },
                {
                  "size": 10,
                  "pattern": "MM/dd/yyyy"
                }
              ]
            }
          }
        }
      ]
    }
    
  • כדי לעצב שדות של 26 בייטים שמסתיימים ב--TIMESTAMP, ב-_TIMESTAMP, ב--TS או ב-_TS כ-TIMESTAMP עם התבנית yyyy-MM-dd HH.mm.ss.SSSSSS, ולהסיר את הסיומת משמות עמודות הפלט:

    {
      "field_suffixes": [
        {
          "suffix": "TIMESTAMP",
          "modifier": {
            "format_timestamp": {
              "formats": [
                {
                  "size": 26,
                  "pattern": "yyyy-MM-dd HH.mm.ss.SSSSSS"
                }
              ]
            }
          }
        },
        {
          "suffix": "TS",
          "modifier": {
            "format_timestamp": {
              "formats": [
                {
                  "size": 26,
                  "pattern": "yyyy-MM-dd HH.mm.ss.SSSSSS"
                }
              ]
            }
          }
        }
      ],
      "transformations": [
        {
          "rename": {
            "find": "^(.*)[-_](TIMESTAMP|TS)$",
            "replace": "$1"
          }
        }
      ]
    }
    

תמיכה באינדיקטורים של ערכים ריקים (null)

‫Mainframe Connector תומך באינדיקטורים של ערכי null באמצעות משתנה השדה null_if בהגדרות של ממיר הקידוד (--transcode-configuration).

כדי להגדיר אינדיקטור null שמבוסס על סיומת (כאשר שדה כמו COL1-NID משמש כאינדיקטור null עבור COL1 באותה רשומה), מגדירים רשומה ב-field_suffixes עם "is_inverse": true ו-"target_field": "$self":

{
  "field_suffixes": [
    {
      "suffix": "NULL_INDICATOR_NAME",
      "is_inverse": true,
      "modifier": {
        "null_if": {
          "target_field": "$self",
          "null_value": "NULL_VALUE",
          "non_null_value": "NOT_NULL_VALUE"
        }
      }
    }
  ]
}

ברשימה הבאה מתוארים הפרמטרים שבהם אפשר להשתמש כדי להגדיר אינדיקטורים של ערכים ריקים:

  • ‫suffix: תואם לסיומות -NULL_INDICATORNAME או NULL_INDICATOR_NAME שמזהות שדה של אינדיקטור null ב-copybook.
  • ‫is_inverse: כשהערך מוגדר כ-true ב-FieldSuffix, המגדיר חל על השדה המקביל ששמו תואם לשדה האינדיקטור בלי הסיומת (לדוגמה, COL1 כשהאינדיקטור הוא COL1-NID1), ו-"$self" מתייחס לשדה האינדיקטור עצמו. אפשר גם להחיל את null_if ישירות על שדה ספציפי באמצעות field_overrides, ולהגדיר את target_field לשם של שדה האינדיקטור.
  • ‫null_value או null_values: מציין את הערך היחיד (null_value) או את רשימת הערכים (null_values) ב-target_field שמציינים שהשדה שאליו מתייחסים הוא null.
  • ‫non_null_value או non_null_values: (אופציונלי) מציין את הערך היחיד (non_null_value) או את רשימת הערכים (non_null_values) ב-target_field כדי לאותת שהשדה שאליו מתייחסים הוא לא null. אם משמיטים את הפרמטר, כל ערך שהוא לא null_value או null_values נחשב כערך שהוא לא null. צריך לציין לפחות אחד מהשדות null_value(s) או non_null_value(s).
  • החרגה או שמירה של שדה אינדיקטור הערך הריק: כברירת מחדל, שדה אינדיקטור הערך הריק נשמר כעמודה בסכימת הפלט. כדי להשמיט את השדה של האינדיקטור לערך null מטבלת הפלט, אבל עדיין להשתמש בו במהלך המרת הקידוד, מוסיפים טרנספורמציה מסוג exclude לשדה האינדיקטור במערך transformations (אל תפעילו את המשנה filler על שדה של אינדיקטור לערך null, כי filler מדלג על פענוח השדה לחלוטין).
  • שינוי סוג השדה של האינדיקטור: (אופציונלי) כדי לאלץ פענוח של שדה אינדיקטור null כ-bytes או כ-binary, מוסיפים כלל field_suffixes (או field_overrides) לא הפוך לשדה האינדיקטור עם "modifier": { "bytes": {} } או "modifier": { "binary": {} }. ב-bytes, צריך לבטא את null_value ו-non_null_value כמחרוזות הקסדצימליות (לדוגמה, "FF" או "00").

דוגמאות

בדוגמאות הבאות, הערכים COL1-NID1 ו-FIELD-NID2 לא נכללים בטבלת הפלט אחרי שהם הוערכו כאינדיקטורים של ערך null, ואילו הערך COL2-NULL נשמר בסכימת הפלט.

קטע קוד של Copybook:

01 REC.
   10 COL1-NID1 PIC S9(4) USAGE COMP.
   10 COL1      PIC S9(6) USAGE COMP.
   10 FIELD     PIC X(10).
   10 FIELD-NID2 PIC X(1).
   10 COL2      PIC X(10).
   10 COL2-NULL PIC X(1).

הגדרת המרת קידוד (transcode-configuration.json):

{
  "field_suffixes": [
    {
      "suffix": "NID1",
      "is_inverse": true,
      "modifier": {
        "null_if": {
          "target_field": "$self",
          "null_value": "-1",
          "non_null_value": "0"
        }
      }
    },
    {
      "suffix": "NID2",
      "is_inverse": true,
      "modifier": {
        "null_if": {
          "target_field": "$self",
          "null_value": "?"
        }
      }
    },
    {
      "suffix": "NULL",
      "is_inverse": true,
      "modifier": {
        "null_if": {
          "target_field": "$self",
          "null_value": "?"
        }
      }
    }
  ],
  "transformations": [
    {
      "exclude": {
        "field": "COL1-NID1"
      }
    },
    {
      "exclude": {
        "field": "FIELD-NID2"
      }
    }
  ]
}

תמיכה בשדות DBCS

כשמשתמשים בשדות DBCS (PIC G או PIC N עם USAGE DISPLAY-1), צריך לוודא את הפרטים הבאים:

  • בשדות PIC G צריך לציין במפורש את USAGE DISPLAY-1.
  • שדות PIC N ללא סעיף USAGE מוגדרים כברירת מחדל ל-USAGE NATIONAL (UTF-16BE). כדי להתייחס לשדה PIC N כשדה DBCS, צריך לציין USAGE DISPLAY-1 ב-copybook (או לשנות את הקידוד שלו בהגדרת הטרנסקודר).
  • כברירת מחדל, השדות של USAGE DISPLAY-1 מפוענחים ומקודדים באמצעות ערכת התווים cp300 (x-IBM300) של DBCS, שמצפה לבייטים גולמיים של DBCS בלי תווי בקרה של shift-out (0x0E) ו-shift-in (0x0F).
  • כדי להשתמש בערכת תווים אחרת של DBCS (כמו Cp834) או בערכת תווים של מספר בייטים (MBCS) שמשתמשת בבייטים של shift-out‏ (0x0E) ו-shift-in‏ (0x0F) (כמו x-IBM930,‏ x-IBM933,‏ x-IBM935,‏ x-IBM937,‏ x-IBM939,‏ x-IBM942,‏ x-IBM942C,‏ x-IBM943,‏ x-IBM943C,‏ x-IBM949,‏ x-IBM949C,‏ x-IBM950,‏ x-IBM964,‏ x-IBM970 או x-IBM1364), צריך להגדיר את משנה השדה string בהגדרות של הטרנסקודר (--transcode-configuration).

אפשר להגדיר את קידוד ה-DBCS באופן גלובלי לכל השדות של USAGE DISPLAY-1 באמצעות defaults.dbcs, או לשדות ספציפיים באמצעות field_overrides או field_suffixes:

{
  "defaults": {
    "dbcs": {
      "string": {
        "encoding": "x-IBM930"
      }
    }
  }
}

תמיכה במחרוזות תווים באורך משתנה

מנתח ה-copybook תומך בשדות של קבוצות מחרוזות תווים באורך משתנה, באמצעות משנה השדה varlen בהגדרות של ממיר הקידוד:

10 VAR-GRP.
   15 VAR-LEN  PIC 9(4) USAGE COMP.
   15 VAR-TEXT PIC X(50).

כשמשתמשים בשינוי השדה varlen, חשוב לוודא את הדברים הבאים:

  • מחילים את המשתנה varlen על הפריט הקבוצתי (לדוגמה, VAR-GRP) באמצעות field_overrides או field_suffixes בהגדרות של הטרנסקודר:

    {
      "field_overrides": [
        {
          "field": "VAR-GRP",
          "modifier": {
            "varlen": {}
          }
        }
      ]
    }
    
  • הפריט הקבוצתי חייב להכיל בדיוק שני שדות משנה:

    1. שדה המשנה הראשון צריך להיות מפוענח למספר שלם של 64 ביט (LONG, כמו שדה של מספר שלם בינארי COMP או עשרוני מוגדר) שמציין את אורך הבייטים של נתוני המחרוזת.
    2. שדה המשנה השני חייב להיות שדה מחרוזת ללא שינוי (כמו PIC X(n),‏ PIC N(n) או PIC U(n)).
  • לא נדרשות סיומות ספציפיות של שדות משנה (כמו -LEN או -TEXT), והעמודה שנוצרת בסכימת הפלט משתמשת בשם של פריט הקבוצה (VAR-GRP).

שדות ומבנים שלא נתמכים

בקטעים הבאים מתוארים השדות והמבנים שלא נתמכים על ידי מנתח ה-copybook.

מבני COBOL שלא נתמכים

מנתח ה-copybook יכול לנתח את מבני ה-COBOL הבאים, למרות שהם לא נתמכים. אם תשתמשו במבנים האלה ב-copybook, תופיע שגיאה ב-Mainframe Connector:

  • ALIGNED
  • BLANK WHEN ZERO
  • COMMON, OWN, LOCAL
  • DYNAMIC LENGTH (כמו PIC X DYNAMIC LENGTH או PIC U DYNAMIC LENGTH LIMIT n)
  • INTEGER, STRING
  • JUSTIFIED
  • ASCENDING/DESCENDING KEY בOCCURS
  • INDEXED BY בOCCURS
  • RECEIVED BY
  • RECORD AREA
  • RENAMES
  • SYNCHRONIZED / SYNC
  • THREAD-LOCAL
  • TYPE IS ...
  • TYPEDEF
  • USING LANGUAGE/CONVENTION

סוגי נתונים לא נתמכים

הדקדוק יכול לנתח את הסוגים הבאים של USAGE, אבל המהדר של ה-copybook לא תומך בהם:

  • BIT
  • CONTROL-POINT
  • DATE
  • DOUBLE
  • EVENT
  • FUNCTION-POINTER
  • INDEX
  • KANJI
  • LOCK
  • POINTER
  • PROCEDURE-POINTER
  • REAL
  • SQL
  • TASK