הכלי 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-5COMP-3,COMPUTATIONAL-3,PACKED-DECIMALCOMP-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": {} } } ] }הפריט הקבוצתי חייב להכיל בדיוק שני שדות משנה:
- שדה המשנה הראשון צריך להיות מפוענח למספר שלם של 64 ביט (
LONG, כמו שדה של מספר שלם בינאריCOMPאו עשרוני מוגדר) שמציין את אורך הבייטים של נתוני המחרוזת. - שדה המשנה השני חייב להיות שדה מחרוזת ללא שינוי (כמו
PIC X(n),PIC N(n)אוPIC U(n)).
- שדה המשנה הראשון צריך להיות מפוענח למספר שלם של 64 ביט (
לא נדרשות סיומות ספציפיות של שדות משנה (כמו
-LENאו-TEXT), והעמודה שנוצרת בסכימת הפלט משתמשת בשם של פריט הקבוצה (VAR-GRP).
שדות ומבנים שלא נתמכים
בקטעים הבאים מתוארים השדות והמבנים שלא נתמכים על ידי מנתח ה-copybook.
מבני COBOL שלא נתמכים
מנתח ה-copybook יכול לנתח את מבני ה-COBOL הבאים, למרות שהם לא נתמכים. אם תשתמשו במבנים האלה ב-copybook, תופיע שגיאה ב-Mainframe Connector:
ALIGNEDBLANK WHEN ZEROCOMMON,OWN,LOCALDYNAMIC LENGTH(כמוPIC X DYNAMIC LENGTHאוPIC U DYNAMIC LENGTH LIMIT n)INTEGER,STRINGJUSTIFIEDASCENDING/DESCENDING KEYבOCCURSINDEXED BYבOCCURSRECEIVED BYRECORD AREARENAMESSYNCHRONIZED/SYNCTHREAD-LOCALTYPE IS ...TYPEDEFUSING LANGUAGE/CONVENTION
סוגי נתונים לא נתמכים
הדקדוק יכול לנתח את הסוגים הבאים של USAGE, אבל המהדר של ה-copybook לא תומך בהם:
BITCONTROL-POINTDATEDOUBLEEVENTFUNCTION-POINTERINDEXKANJILOCKPOINTERPROCEDURE-POINTERREALSQLTASK