| Quick Reference |
このドキュメントでは、タイプがファンクションの Natural オブジェクトを使用して実装される関数について説明します。
これらのファンクションオブジェクト（およびそのプロトタイプ定義）のうち、その名前が SAG で始まるものは、システムファイル FNAT の Natural システムライブラリ SYSTEM で提供されています。システムライブラリ SYSEXPG には、サンプルファンクションコールが用意されています。
ファンクションコールの詳細については、『プログラミングガイド』ドキュメントの関連セクションを参照してください。
Natural アプリケーションを HTTP 要求とインターフェイスで接続する場合、URI（Uniform Resource Identifier）が URL エンコードされている必要があります。REQUEST DOCUMENT ステートメントには、ドキュメントにアクセスするためにこのような URL が必要です。
URL エンコード（またはパーセントのエンコーディング）とは、URL の一部の特殊文字を置き換えるメカニズムです。US-ASCII 文字セットの文字のみを使用して URL を形成できます。US-ASCII 文字セットの一部の文字は、URL で使用される場合に特別な意味を持ちます。これらの文字は"予約されている"制御文字として分類され、URL 文字列を異なる意味を持つサブコンポーネントに構造化します。URL の一般的な構文に関する準標準は、RFC 3986（インターネットコミュニティで構成されるドキュメント）に規定されています。URL エンコードが必要な条件について説明しています。これには、US-ASCII 文字セット（ユーロ記号など）に含まれていない文字の表現、および予約されている文字の使用についての説明が含まれます。
予約されている文字は以下のとおりです。
| ? | = | & | # | ! | $ | % | ' | ( | ) | * | + | , | / | : | ; | @ | [ | ] |
予約されていない文字は以下のとおりです。
| A～Z | a～z | 0-9 | - | _ | . | ~ |
URL には、予約されている文字と予約されていない文字のみを使用できます。他の文字は使用できません。（予約されている文字と予約されていない文字のいずれにも該当しない）他のバイト値が必要な場合、または予約されている文字が（URL コンテキストで特別な意味を持たない）データとして使用されている場合、Windows-1252
エンコードスキーマにより、直後にコードポイントを表す 2 桁の 16 進数が続くこれらのコードは、"%-encoding" 形式（パーセント記号）に変換する必要があります。これにより、文字列でプラス記号（+）が %2B、パーセント記号（%）が %25、アットマーク（@）が %40 として表示されます。
以下のエンコード関数は、入力文字列全体を処理します。パーセント形式に変換してはいけない制御文字（予約されている文字）が含まれている場合、URL 全体またはその一部をエンコードしないでください。これらの関数は、URL での使用を許可されていない文字、およびデータ項目として提供される URL コンテキスト内で特別な意味を持つ文字にのみ適用する必要があります。
単一の入力パラメータに、エンコードまたはデコードされる文字列が含まれます。内部のすべてのデータは、現在どのセッションコードページが実際にアクティブになっているかにかかわらず、コードページ Windows-1252 で表されているものと見なされます。SAGENC/SAGDEC 関数の実行には Unicode のサポートは必要ありません。以下の文字は、対応する US-ASCII 16 進数で置き換えられます。
|
文字
|
< | ( | + | | | & | ! | $ | * | ) | ; | / | , | % | > | ? | ` | : | # | @ | ' | = | " | ^ | [ | ] | { | } | \ |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| %nn にエンコードされます | 3C | 28 | 2B | 7C | 26 | 21 | 24 | 2A | 29 | 3B | 2F | 2C | 25 | 3E | 3F | 60 | 3A | 23 | 40 | 27 | 3D | 22 | 5E | 5B | 5D | 7B | 7D | 5C |
さらにスペースはプラス記号（+）に置き換えられます。他のすべての文字は元のままで変換されません。単一のエンコード関数は、ほとんどの場合、URL エンコードで十分です。返される結果フィールドのフォーマットは、A ダイナミックです。
次の機能を使用できます。
この関数 SAGENC は、文字列をパーセントエンコード形式にエンコードします。標準 RFC3986 に従い、（URL では許可されていない）US-ASCII x'7F' 未満の文字と予約されている文字はパーセントでエンコードされ、スペース文字はプラス記号（+）に置き換えられます。予約されていない文字は RCF3986 に準拠し、（ドイツ語のウムラウトなど）US-ASCII x'7F' より上の文字はエンコードされません。このような文字をエンコードする場合は、拡張エンコード関数 SAGENCE を使用します。
| オブジェクト | 説明 |
|---|---|
SAGENC |
これは単一のエンコードファンクションコールです。 |
SAGENCP |
プロトタイプ定義を含むコピーコードは、必要に応じて、ファンクションコール参照の戻り変数のタイプを決定してパラメータをチェックするのみの目的で、コンパイル時に使用されます。
|
URLX01 |
ライブラリ SYSEXPG に含まれるプログラム例。#URL-ENC := SAGENC(<#URL-DEC>) |
関数 SAGDEC によって、関数 SAGENC が提供したパーセントのエンコーディングがデコードされます。入力パラメータはデコード文字列以外に必要ありません。
| オブジェクト | 説明 |
|---|---|
SAGDEC |
これは単一のデコードファンクションコールです。 |
SAGDECP |
プロトタイプ定義を含むコピーコードは、必要に応じて、ファンクションコール参照の戻り変数のタイプを決定してパラメータをチェックするのみの目的で、コンパイル時に使用されます。
|
URLX01 |
ライブラリ SYSEXPG に含まれるプログラム例。#URL-DEC := SAGDEC(<#URL-ENC>) |
拡張関数は、RFC 3986 で指定または推奨されているすべての問題を考慮します。以下のパラメータが考慮されます（デフォルト設定は太字で表示）。
エンコード／デコードされる <dynamic U-string>
リターンコード：<> 0（Natural エラー）MOVE
ENCODED ステートメントにエラーがある場合。
リターンコード <> 0 の場合エラー文字
スペース文字：%20/+/エンコードしない（デフォルト：+）
予約されていない文字：エンコード／エンコードしない
予約されている文字：エンコード／エンコードしない
その他の特殊文字（予約されていない文字、予約されている文字のいずれでもない）：エンコード／エンコードしない
文字のパーセントによるエンコード：ISO-8859-1/UTF-8/その他のコードページ/if='' then *CODEPAGE（デフォルトのエンコードコードコードページではなく、デフォルトの Natural コードページ）
フォーマット U の X-array でユーザーが選択した文字。この文字は、上記のパラメータに従ったパーセントによるエンコードは行われません。例えば、ISO-8859-1 コードページにはないユーロ記号の場合、または文字のパーセントによるエンコードを防ぐ場合などです。
X-array と同じオカレンスにある、ユーザーが選択した文字に対する、フォーマット A のX-array 内でのユーザー定義のパーセントによるエンコード。
文字列の入力パラメータは Natural フォーマット U になります。これは、入力文字列にはすべての Unicode 文字を含めることができることを意味します。拡張関数の出力文字列は、Natural デフォルトコードページ（*CODEPAGE）のフォーマット A です。パーセントによるエンコードのコードページを選択できます。UTF-8、ISO-8859-1、ユーロ記号のパーセントによるエンコードは、MOVE
ENCODED ステートメントによって実行されます。パーセントによるエンコードに使用されるターゲットコードページに入力文字が存在しない場合、その文字はエンコードされません。これは、デフォルトの Natural コードページで文字が変更されずに返されることを意味します。文字がデフォルトの
Natural コードページに存在しない場合、その文字は MOVE ENCODED ステートメントによって返される置換文字に置き換えられます。置換文字はパーセントによりエンコードされます。これは、パーセントによるエンコードのコードページが UTF-8 でない場合にのみ発生する可能性があります。最後の MOVE ENCODED エラーが返されます。
パラメータはオプションのパラメータです。ユーザーがパラメータを指定しない場合は、デフォルト値が使用されます。ユーザーが独自の文字変換テーブルを指定した場合、テーブル内の文字は、他のパラメータではなく、このテーブルに従ってパーセントによりエンコードされます。ユーザー定義の変換テーブルの文字をパーセントによりエンコードしたものが同じ文字または空白に等しい場合、この文字はエンコードされません。このようにして、予約されている文字セットまたは予約されていない文字セットから単一の文字を除外できます。
次の機能を使用できます。
SAGENCE - 拡張エンコード（フォーマット U からフォーマット A、オプションのパラメータ）
SAGDECE - 拡張デコード（フォーマット A からフォーマット U、オプションのパラメータ）
関数 SAGENCE は選択したコードページ（デフォルトは UTF-8）の 16 進値を使用して文字列をパーセントによりエンコードします。標準 RFC3986 に従い、予約されている文字と（URL では許可されていない）US-ASCII x'7F' 未満の文字はパーセントによりエンコードされます。また、スペースとパーセント記号（%）もエンコードされます。
さらに、RCF3986 に準拠した予約されていない文字と、ドイツ語のウムラウトなどの US-ASCII x'7F' より上位の文字がこの関数によってエンコードされます。
SAGENCE には Natural Unicode のサポートが必要です。
| オブジェクト | 説明 |
|---|---|
SAGENCE |
これは拡張エンコードファンクションコールです。 |
| Parameters: | |
P-DEC-STR-E (U)
P-RET (I4) OPTIONAL /* 0: ok
/* else: Natural error returned
/* by the GIVING clause of
/* MOVE ENCODED.
/* This is the error which
/* comes up when a character
/* cannot be converted into
/* the target code page.
/* Error strategy:
/* Step 1: If a character shall be %-encoded and is not available
/* in the code page for %-encoding, the character will not be
/* %-encoded. It will be copied.
/* Step 2: If a character will not be %-encoded but copied from the
/* input format U-variable to a format A-variable (in *CODEPAGE)
/* and the character is not available in *CODEPAGE, a substitution
/* character will be used instead. The substitution character will
/* be %-encoded.
/* The last error will be returned in P-RET.
P-ERR-CHAR (U1) OPTIONAL /* Character causing the error
P-SPACE (A1) OPTIONAL /* '%' => %20
/* ' ' => ' '
/* else => '+' (default)
P-UNRES (A1) OPTIONAL /* 'E' => encode
/* else => don't encode (default)
P-RES (A1) OPTIONAL /* 'E' => encode (default)
/* else => don't encode
P-OTHER (A1) OPTIONAL /* 'E' => encode (default)
/* else => don't encode
P-CP (A64) OPTIONAL /* IANA name e.g. UTF-8 (default)
/* or ISO-8859-1
/* On mainframe only code page names defined with the macro NTCPAGE
/* in the source module NATCONFG can be used. Other code page names
/* are rejected with a corresponding runtime error.
/*
P-CP-TABLE-CHAR(U1/1:*) OPTIONAL /* user selected char to be
/* %-encoded, e.g. 'ö' or '/'
P-CP-TABLE-ENC (A12/1:*) OPTIONAL /* user %-encoding
/* e.g. character 'ö'
/* '%F6' -> ISO-8859-1
/* '%C3%B6' -> UTF-8
/* e.g. character '/'
/* '/' -> '/' not encoded
/* although P-RES = 'E'
/* Characters in this table will be encoded according to the
/* specifed %-encoding. If the U12 encoding part is blank (space
/* according to *CODEPAGE) or the P-CP-TABLE-ENC value is equal to
/* the character, then the character will not be encoded at all.
/* |
|
SAGENCEP |
プロトタイプ定義を含むコピーコードは、必要に応じて、ファンクションコール参照の戻り変数のタイプを決定してパラメータをチェックするのみの目的で、コンパイル時に使用されます。
|
URLX01 |
ライブラリ SYSEXPG に含まれるプログラム例。
|
|
サンプル呼び出し 以下のデフォルト値が使用されます。 #URL-ENC := SAGENCE(<#URL-DEC-U>) 使用可能なパラメータがすべて指定されます。 #URL-ENC := SAGENCE(<#URL-DEC-U,L-RET,L-ERR-CHAR,L-SPACE,L-UNRES, L-RES,L-OTHER,L-CP,L-CP-TAB-CHAR(*),L-CP-TAB-ENC(*) >) |
関数 SAGDECE によって、関数 SAGENCE が提供したパーセントのエンコーディングがデコードされます。スペース文字および／またはコードページが指定されている場合、値はエンコードに指定されている値と同じであることが必要です。
SAGDECE には Natural Unicode のサポートが必要です。
| オブジェクト | 説明 |
|---|---|
SAGDECE |
これは拡張デコーディングファンクションコールです。 |
| Parameters: | |
1 P-ENC-STR-E (A)
1 P-RET (I4) OPTIONAL /* 0: ok
/* else: Natural error returned
/* by the GIVING clause of
/* MOVE ENCODED.
/* This error comes up
/* when a %-encoded
/* character cannot be
/* converted into the
/* target code page.
/* The last error will be returned in P-RET.
1 P-ERR-CHAR (A12) OPTIONAL /* Error character %-encoded
1 P-SPACE (A1) OPTIONAL /* ' ' => ' '
/* else => '+' (default)
1 P-CP (A64) OPTIONAL /* IANA name e.g. UTF-8 (default)
/* or ISO-8859-1
/* On mainframe only code page names defined with the macro NTCPAGE
/* in the source module NATCONFG can be used. Other code page names
/* are rejected with a corresponding runtime error.
/* |
|
SAGDECEP |
プロトタイプ定義を含むコピーコードは、必要に応じて、ファンクションコール参照の戻り変数のタイプを決定してパラメータをチェックするのみの目的で、コンパイル時に使用されます。
|
URLX01 |
ライブラリ SYSEXPG に含まれるプログラム例。
|
|
サンプル呼び出し 以下のデフォルト値が使用されます。 #URL-DEC-U := SAGDECE(<#URL-ENC>) 使用可能なパラメータがすべて指定されます。 #URL-DEC-U := SAGDECE(<#URL-ENC,L-RET,L-ERR-CHAR-DEC,L-SPACE,L-CP>) |
ライブラリ SYSEXPG に含まれるプログラム例。
** Example 'URLX01': ENCODED-STR := SAGENC(<DECODED-STR>)
************************************************************************
DEFINE DATA
LOCAL
1 SAMPLE-STRING (A72)
/*
1 #URL-DEC (A) DYNAMIC
1 #URL-ENC (A) DYNAMIC
/*
1 #URL-DEC-U (U) DYNAMIC
/*
1 L-RET (I4) /* Return code
1 L-ERR-CHAR (U1) /* Error character
1 L-ERR-CHAR-DEC(A12) /* Decoded error character
1 L-SPACE (A1) /* '%' => %20, ' ' => ' ',
/* else => '+' (default)
1 L-UNRES (A1) /* 'E' => encode, else => don't encode (default)
1 L-RES (A1) /* 'E' => encode (default), else => don't encode
1 L-OTHER (A1) /* 'E' => encode (default), else => don't encode
1 L-CP (A64) /* default *CODEPAGE
1 L-CP-TAB-CHAR (U1/1:1)
1 L-CP-TAB-ENC (A12/1:1)
1 L-MSG (U72)
END-DEFINE
/*
/*
/*
WRITE 'Sample string to be processed:'
/* The string below shall be encoded and decoded again.
/* After decoding it should be unchanged.
SAMPLE-STRING := '"Decoded data!"'
WRITE SAMPLE-STRING (AL=72) /
/*
/* Assign the sample string to the input variable #URL-DEC of the
/* simple encoding function.
#URL-DEC := SAMPLE-STRING
/*
/* Copycode SAGENCP containing the prototype definition is used at
/* compilation time only in order to determine the type of the return
/* variable for function call reference and to check the parameters,
/* if this is desired. SAGENCP is optional.
INCLUDE SAGENCP
/*
/* SAGENC(<#URL-DEC>) is the simple encoding function call.
/*
/* Function SAGENC %-encodes a string to code page ISO-8859-1.
/* According to standard RFC3986 reserved characters and characters
/* below US-ASCII x'7F' which are not allowed in a URL will be
/* %-encoded.
/* Also the space and the percent sign will be encoded.
/* Unreserved characters according to RCF3986 and characters above
/* US-ASCII x'7F' will not be encoded. If you want to encode such
/* characters, use the extended encoding function.
/*
/* ---- Space ' ' -> '+'
/* ---- Percent sign '%' -> '%25'
/*
/* Unreserved characters according to RFC3986 (will not be encoded!):
/* ---- Period (fullstop) '.' -- '%2E'
/* ---- Tilde '~' -- '%7E'
/* ---- Hyphen '-' -- '%2D'
/* ---- Underscore character '_' -- '%5F'
/* ---- digits, lower and upper case characters
/* ---- 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
/*
/* Reserved characters according to RFC3986:
/* ---- Exclamation mark '!' -> '%21'
/* ---- Number sign '#' -> '%23'
/* ---- Dollar sign '$' -> '%24'
/* ---- Ampersand '&' -> '%26'
/* ---- Apostrophe ''' -> '%27'
/* ---- Left parenthesis '(' -> '%28'
/* ---- Right parenthesis ')' -> '%29'
/* ---- Asterisk '*' -> '%2A'
/* ---- Plus sign '+' -> '%2B'
/* ---- Comma ',' -> '%2C'
/* ---- Reverse solidus (backslash) '/' -> '%2F'
/* ---- Colon ':' -> '%3A'
/* ---- Semi-colon ';' -> '%3B'
/* ---- Equals sign '=' -> '%3D'
/* ---- Question mark '?' -> '%3F'
/* ---- Commercial at '@' -> '%40'
/* ---- Square bracket open '[' -> '%5B'
/* ---- Square bracket close ']' -> '%5D'
/*
/* Other characters below x'7F' (US-ASCII) but not allowed in URL
/* ---- Quotation mark '"' -> '%22'
/* ---- Less than '<' -> '%3C'
/* ---- Greater than '>' -> '%3E'
/* ---- Reverse solidus (backslash) '\' -> '%5C'
/* ---- Accent, Circumflex '^' -> '%5E'
/* ---- Accent, Grave '`' -> '%60'
/* ---- Opening brace '{' -> '%7B'
/* ---- Vertical bar '|' -> '%7C'
/* ---- Closing brace '}' -> '%7D'
/*
#URL-ENC := SAGENC(<#URL-DEC>)
/*
/*
WRITE 'Simple function, encoded:'
WRITE #URL-ENC (AL=72)
/*
/* Copycode SAGDECP containing the prototype definition is used at
/* compilation time only in order to determine the type of the return
/* variable for function call reference and to check the parameters,
/* if this is desired. SAGDECP is optional.
INCLUDE SAGDECP
/*
/* SAGDEC(<#URL-ENC>) is the simple decoding function call.
/* It decodes the above described %-encodings.
/*
#URL-DEC := SAGDEC(<#URL-ENC>)
/*
/*
/* The result after encoding and decoding must be equal to the original
/* SAMPLE-STRING.
WRITE 'Simple function, decoded:'
WRITE #URL-DEC (AL=72)
/*
/*
/*
WRITE /
/*
/*
/*
/* Assign the sample string to the input variable #URL-DEC-U of the
/* enhanced encoding function.
#URL-DEC-U := SAMPLE-STRING
/*
/* Copycode SAGENCEP containing the prototype definition is used at
/* compilation time only in order to determine the type of the return
/* variable for function call reference and to check the parameters,
/* if this is desired. SAGENCEP is optional.
INCLUDE SAGENCEP
/*
/* This is the enhanced encoding function call.
/* The way, characters will be %-encoded dependes on the input
/* parameter of the function.
/* The parameters of the encoding and decoding function are preset
/* with the default values.
/* L-CP-TAB-CHAR(*) and L-CP-TAB-ENC(*) don't have default values.
/* L-CP-TAB-CHAR(1) = 'ä' and L-CP-TAB-ENC(1) = '%C3%A4' will not be
/* used for the sample string '"Decoded data!"'. The string does not
/* contain an 'ä'.
L-SPACE := '+' /* encoding and decoding
L-UNRES := 'D' /* encoding only
L-RES := 'E' /* encoding only
L-OTHER := 'E' /* encoding only
L-CP := 'UTF-8' /* encoding and decoding
/* e.g. ISO-8859-1, UTF-16BE, UTF-32BE
L-CP-TAB-CHAR(1) := 'ä' /* encoding only
L-CP-TAB-ENC (1) := '%C3%A4' /* encoding only
/*
/* Note that all possible parameters are specified for this sample
/* call.
/* If the default values shall be used and no return code is wanted,
/* all parameters can be omitted, besides the string #URL-DEC-U.
/*
#URL-ENC := SAGENCE(<#URL-DEC-U,L-RET,L-ERR-CHAR,L-SPACE,L-UNRES,
L-RES,L-OTHER,L-CP,L-CP-TAB-CHAR(*),L-CP-TAB-ENC(*) >)
WRITE 'Extended function, encoded:'
WRITE #URL-ENC (AL=72)
IF L-RET NE 0 THEN
/* If L-RET = 0, the function worked ok. Else L-RET contains the
/* Natural error returned by the GIVING clause of MOVE ENCODED.
/* The error comes up when a character cannot be converted into
/* the target codepage, e.g. because a character does not exist
/* in the target codepage.
COMPRESS 'Error' L-RET 'with MOVE ENCODED of' L-ERR-CHAR INTO L-MSG
WRITE L-MSG
END-IF
/*
/* Copycode SAGDECEP containing the prototype definition is used at
/* compilation time only in order to determine the type of the return
/* variable for function call reference and to check the parameters,
/* if this is desired. SAGDECEP is optional.
INCLUDE SAGDECEP
/*
/* This is the 1st enhanced decoding function call with 5 parameters.
/* Note that all possible parameters are specified for this sample
/* call.
/* Since the parameters have the default values, the subsequent
/* function calls return the same result although parameters
/* have been omitted.
#URL-DEC-U := SAGDECE(<#URL-ENC,L-RET,L-ERR-CHAR-DEC,L-SPACE,L-CP>)
WRITE 'Extended function, decoded:'
WRITE #URL-DEC-U (AL=72)
IF L-RET NE 0 THEN
/* If L-RET = 0, the function worked ok. Else L-RET contains the
/* Natural error returned by the GIVING clause of MOVE ENCODED.
/* The error comes up when a %-encoded character cannot be converted
/* into the target codepage, e.g. because a character does not exist
/* in the target codepage.
COMPRESS 'Error' L-RET 'with MOVE ENCODED of' L-ERR-CHAR INTO L-MSG
WRITE L-MSG
RESET L-RET
END-IF
/*
/* This is the 2nd enhanced decoding function call with one parameter.
#URL-DEC-U := SAGDECE(<#URL-ENC>)
WRITE #URL-DEC-U (AL=72)
/* L-RET will not be returned
/*
/* This is the 3rd enhanced decoding function call with 3 parameters.
#URL-DEC-U := SAGDECE(<#URL-ENC,L-RET,2X,L-CP>)
WRITE #URL-DEC-U (AL=72)
IF L-RET NE 0 THEN
COMPRESS 'Error' L-RET 'with MOVE ENCODED of' L-ERR-CHAR INTO L-MSG
WRITE L-MSG
RESET L-RET
END-IF
/*
END
このセクションでは、Base64 変換を使用して、バイナリデータを出力可能なネットワーク互換データに、またはその逆方向に変換するために使用できる Natural 関数について説明します。
Base64 変換とは、フォーマット B から フォーマット A に変換し、フォーマット A からフォーマット B に戻すことを意味します。ここで、6（バイナリ）ビットは 8（英数字）ビットに変換されます。例えば、B3 の値は A4 の値に変換されます。
注意:
各バイナリ値は、あいまいでない英数字の値に変換されます。この英数字の値を再変換すると、元の 2 進値になります。ただし、フォーマット A からフォーマット B、フォーマット B からフォーマット A への変換のほとんどが、これに該当しません。
この変換は、TCP/IP 経由で .bmp ファイルを転送したり、ユーティリティプロトコルを介して Natural バイナリ値や整数値を転送したりするために使用できます。
Open Systems のみ：次の 3 つのモードを使用できます。RFC3548、RFC2045、およびNATRPC（デフォルト）。NATRPC は、変換が NATRPC ロジックに従って実行されることを意味します。これは 100% メインフレーム対応です。RFC2045 は、CMBASE64 コールのデフォルトです。RFC3548 は NATRPC と同じですが、必要のない英数字バイトには等号（=）が入力されます。
次の機能を使用できます。
これらの 2 つの関数は、ライブラリ SYSEXT に提供される Natural アプリケーションプログラムインターフェイス USR4210N と同じ機能を提供します。
この関数 SAG64BA は、Base64 エンコードを使用して、バイナリデータを出力可能なネットワーク互換データに変換します。
| オブジェクト | 説明 |
|---|---|
SAG64BA |
これは、バイナリから英数字フォーマットへの変換関数です。 |
| Parameters: | |
1 PARM-B (B) DYNAMIC BY VALUE
/* Binary source input/target output
1 PARM-RC (I4) OPTIONAL
/* 0: ok
/* Mainframe
/* 1 Source is not numeric
/* 2 Source is not packed
/* 3 Source is not floating point
/* 4 Overflow, source doesn't fit into target
/* 5 Integer overflow
/* 6 Source is not a valid date or time
/* 7 Length error (hex input not even)
/* 8 Target precision is less than source precision
/* 9 Float underflow (result->0)
/* 10 Alpha source contains non-hex characters
/* 20 Invalid function code
/* Open Systems
/* 1 Invalid value for RFC parameter
/* 2 Invalid function code
/* 3 CMBASE64: Overflow, source doesn't fit into
/* target
/* 4 CMBASE64: Non-base64 character found in encoded
/* data
/* 5 CMBASE64: Out of memory
/* 6 CMBASE64: Invalid number of parameters
/* 7 CMBASE64: Invalid parameter type
/* 8 CMBASE64: Invalid parameter length
/* 9 CMBASE64: Invalid function code
/* 10 CMBASE64: Unkown return code
1 PARM-ERRTXT (A72) OPTIONAL
/* blank, if ok no error
/* else error text
1 PARM-RFC (B1) OPTIONAL
/* OS only, not used for MF
/* 0 - RFC3548; 3 - RFC2045; 4 - NATRPC; |
|
SAG64BAP |
プロトタイプ定義を含むコピーコードは、必要に応じて、ファンクションコール参照の戻り変数のタイプを決定してパラメータをチェックするのみの目的で、コンパイル時に使用されます。
|
B64X01 |
ライブラリ SYSEXPG に含まれるプログラム例。
以下のデフォルト値が使用されます。 PARM-A := SAG64BA(<PARM-B>) 使用可能なパラメータがすべて指定されます（ PARM-A := SAG64BA(<PARM-B,PARM-RC,PARM-ERRTXT,PARM-RFC>) |
この関数 SAG64AB は、Base64 エンコードを使用して、出力可能なネットワーク互換データをバイナリデータに変換します。
| オブジェクト | 説明 |
|---|---|
SAG64AB |
これは、英数字からバイナリフォーマットへの変換関数です。 |
| Parameters: | |
1 PARM-A (A)
/* Alpha source input/target output
1 PARM-RC (I4) OPTIONAL
/* 0: ok
/* Mainframe
/* 1 Source is not numeric
/* 2 Source is not packed
/* 3 Source is not floating point
/* 4 Overflow, source doesn't fit into target
/* 5 Integer overflow
/* 6 Source is not a valid date or time
/* 7 Length error (hex input not even)
/* 8 Target precision is less than source precision
/* 9 Float underflow (result->0)
/* 10 Alpha source contains non-hex characters
/* 20 Invalid function code
/* Open Systems
/* 1 Invalid value for RFC parameter
/* 2 Invalid function code
/* 3 CMBASE64: Overflow, source doesn't fit into
/* target
/* 4 CMBASE64: Non-base64 character found in encoded
/* data
/* 5 CMBASE64: Out of memory
/* 6 CMBASE64: Invalid number of parameters
/* 7 CMBASE64: Invalid parameter type
/* 8 CMBASE64: Invalid parameter length
/* 9 CMBASE64: Invalid function code
/* 10 CMBASE64: Unkown return code
1 PARM-ERRTXT (A72) OPTIONAL
/* blank, if ok no error
/* else error text
1 PARM-RFC (B1) OPTIONAL
/* OS only, not used for MF
/* 0 - RFC3548; 3 - RFC2045; 4 - NATRPC; |
|
SAG64ABP |
プロトタイプ定義を含むコピーコードは、必要に応じて、ファンクションコール参照の戻り変数のタイプを決定してパラメータをチェックするのみの目的で、コンパイル時に使用されます。
|
B64X01 |
ライブラリ SYSEXPG に含まれるプログラム例。
以下のデフォルト値が使用されます。 PARM-B := SAG64AB(<PARM-A>) 使用可能なパラメータがすべて指定されます（ PARM-B := SAG64AB(<PARM-A,PARM-RC,PARM-ERRTXT,PARM-RFC>) |
ライブラリ SYSEXPG に含まれるプログラム例 B64X01。
** Example 'B64X01': BASE64-A-STR := SAG64BA(<BASE64-B-STR>)
************************************************************************
* Function ......... Convert binary data into printable,
* network-compatible data or vice versa using
* Base64 encoding.
*
* Base64 encoding means (B) -> (A) -> (B),
* where 6 (binary) bits will be encoded into 8
* (alpha) bits, e.g a (B3) value will be encoded
* into a (A4) value.
*
* Note: Every binary value will be encoded into
* a non-ambiguous alpha value. Re-encoding this
* alpha value again will result in the original
* binary value. However, this is not the case with
* most of the (A) -> (B) -> (A) encodings.
*
* The encoding may be used to transfer a .bmp
* file via TCP/IP, or to transfer Natural binary or
* integer values via the utility protocol.
*
* Open Systems only:
* On Open Systems, there are 3 modes:
* RFC3548, RFC2045 and NATRPC (default).
* NATRPC means the encoding follows
* the NATRPC logic. This is 100% MF compatible.
* RFC2045 is the default of the CMBASE64 call.
* RFC3548 is like NATRPC, but alpha bytes not
* needed are filled with '='.
*
DEFINE DATA
LOCAL
1 FUNCTION (A2)
/* 'AB' Alpha to binary encoding
/* 'BA' Binary to alpha encoding
1 PARM-RC (I4)
/* 0: ok
/* Mainframe
/* 1 Source is not numeric
/* 2 Source is not packed
/* 3 Source is not floating point
/* 4 Overflow, source doesn't fit into target
/* 5 Integer overflow
/* 6 Source is not a valid date or time
/* 7 Length error (hex input not even)
/* 8 Target precision is less than source precision
/* 9 Float underflow (result->0)
/* 10 Alpha source contains non-hex characters
/* 20 Invalid function code
/* Open Systems
/* 1 Invalid value for RFC parameter
/* 2 Invalid function code
/* 3 CMBASE64: Overflow, source doesn't fit into
/* target
/* 4 CMBASE64: Non-base64 character found in encoded
/* data
/* 5 CMBASE64: Out of memory
/* 6 CMBASE64: Inalid number of parameters
/* 7 CMBASE64: Invalid parameter type
/* 8 CMBASE64: Invalid parameter length
/* 9 CMBASE64: Invalid function code
/* 10 CMBASE64: Unkown return code
1 PARM-ERRTXT (A72)
/* blank, if ok no error
/* else error text
1 PARM-A (A) DYNAMIC
/* Alpha source input/target output
1 PARM-B (B) DYNAMIC
* /* Binary source input/target output
1 PARM-RFC (B1)
/* OS only, not used for MF
/* 0 - RFC3548; 3 - RFC2045; 4 - NATRPC;
/*
1 #BACKUP-A (A) DYNAMIC
1 #BACKUP-B (B) DYNAMIC
END-DEFINE
/*
/*
SET KEY ALL
/*
/* Copycode SAG64BAP and SAG64ABP containing the prototype definition
/* is used at compilation time only in order to determine the type of
/* the return variable for function call reference and to check the
/* parameters, if this is desired. SAG64BAP and SAG64ABP are optional.
INCLUDE SAG64BAP
INCLUDE SAG64ABP
/*
REPEAT
RESET PARM-A PARM-B
REDUCE DYNAMIC PARM-A TO 0
REDUCE DYNAMIC PARM-B TO 0
FUNCTION := 'BA'
PARM-B := H'0123456789ABCDEF'
INPUT (AD=MIL IP=OFF CD=NE) WITH TEXT PARM-ERRTXT
// 10T 'Base64 Encoding:' (YEI)
/ 10T '-' (19) (YEI) /
/ 10T 'Function (BA,AB) ..' (TU) FUNCTION (AD=T)
/ 10T 'Alpha In/Output ...' (TU) PARM-A (AL=30)
/ 10T 'Binary In/Output ..' (TU) PARM-B (EM=HHHHHHHH)
/ 10T 'Response ..........' (TU) PARM-RC (AD=OD CD=TU)
/ PARM-ERRTXT (AD=OD CD=TU)
RESET PARM-ERRTXT
IF *PF-KEY NE 'ENTR'
ESCAPE BOTTOM
END-IF
/*
RESET #BACKUP-A #BACKUP-B
REDUCE DYNAMIC #BACKUP-A TO 0
REDUCE DYNAMIC #BACKUP-B TO 0
#BACKUP-A := PARM-A
#BACKUP-B := PARM-B
/*
IF FUNCTION = 'BA'
/* Parameter PARM-RC, PARM-ERRTXT and PARM-RFC are optional
/* Parameter PARM-RFC does not apply to mainframe
/* PARM-A := SAG64BA(<PARM-B,PARM-RC,PARM-ERRTXT,PARM-RFC>)
PARM-A := SAG64BA(<PARM-B,PARM-RC,PARM-ERRTXT>)
/* PARM-A := SAG64BA(<PARM-B,PARM-RC>)
/* PARM-A := SAG64BA(<PARM-B>)
ELSE
/* Parameter PARM-RC, PARM-ERRTXT and PARM-RFC are optional
/* Parameter PARM-RFC does not apply to mainframe
/* PARM-B := SAG64AB(<PARM-A,PARM-RC,PARM-ERRTXT,PARM-RFC>)
PARM-B := SAG64AB(<PARM-A,PARM-RC,PARM-ERRTXT>)
/* PARM-B := SAG64AB(<PARM-A,PARM-RC>)
/* PARM-B := SAG64AB(<PARM-A>)
END-IF
/*
IF PARM-RC NE 0 THEN
WRITE 'Encoding' FUNCTION
WRITE NOTITLE PARM-ERRTXT
ELSE
IF FUNCTION = 'BA' THEN
WRITE 'Binary -> Alpha'
WRITE '=' PARM-B (EM=HHHHHHHHHHHHHHHHHHHHHHHHH)
/ '=' PARM-A (AL=50)
RESET PARM-B
REDUCE DYNAMIC PARM-B TO 0
FUNCTION := 'AB'
ELSE
WRITE 'Alpha -> Binary'
WRITE '=' PARM-A (AL=50) /
'=' PARM-B (EM=HHHHHHHHHHHHHHHHHHHHHHHHH)
RESET PARM-A
REDUCE DYNAMIC PARM-A TO 0
FUNCTION := 'BA'
END-IF
/*
IF FUNCTION = 'BA'
/* Parameter PARM-RC, PARM-ERRTXT and PARM-RFC are optional
/* Parameter PARM-RFC does not apply to mainframe
/* PARM-A := SAG64BA(<PARM-B,PARM-RC,PARM-ERRTXT,PARM-RFC>)
PARM-A := SAG64BA(<PARM-B,PARM-RC,PARM-ERRTXT>)
/* PARM-A := SAG64BA(<PARM-B,PARM-RC>)
/* PARM-A := SAG64BA(<PARM-B>)
ELSE
/* Parameter PARM-RC, PARM-ERRTXT and PARM-RFC are optional
/* Parameter PARM-RFC does not apply to mainframe
/* PARM-B := SAG64AB(<PARM-A,PARM-RC,PARM-ERRTXT,PARM-RFC>)
PARM-B := SAG64AB(<PARM-A,PARM-RC,PARM-ERRTXT>)
/* PARM-B := SAG64AB(<PARM-A,PARM-RC>)
/* PARM-B := SAG64AB(<PARM-A>)
END-IF
IF PARM-RC NE 0 THEN
WRITE 'Encoding' FUNCTION
WRITE NOTITLE PARM-ERRTXT
ELSE
IF FUNCTION = 'BA' THEN
WRITE 'Binary -> Alpha'
WRITE '=' PARM-B (EM=HHHHHHHHHHHHHHHHHHHHHHHHH)
/ '=' PARM-A (AL=50)
IF PARM-A = #BACKUP-A THEN
WRITE '******** Encoding successful ********'
ELSE
WRITE '******** Value changed by encoding ********'
END-IF
ELSE
WRITE 'Alpha -> Binary'
WRITE '=' PARM-A (AL=50) /
'=' PARM-B (EM=HHHHHHHHHHHHHHHHHHHHHHHHH)
IF PARM-B = #BACKUP-B THEN
WRITE '******** Encoding successful ********'
ELSE
WRITE '******** Value changed by encoding ********'
END-IF
END-IF
END-IF
END-IF
END-REPEAT
END