OPTIONS キーワードは、次のようなオプションを渡す 1 つまたは複数のパラメー ターを指定するために使用されます。
OPTIONS(*NOPASS) を定義仕様書に指定した場合には、呼び出し時にパラメーターを渡 す必要はありません。 この指定より後のすべてのパラメーターにも、*NOPASS の指定が必要です。 プログラムまたはプロシージャーにパラメーターが渡されないと、呼び出されたプログラムまたはプロシージャーは、単に、パラメーター・リストにそのパラメーターが含まれていないものとして機能します。 呼び出されたプログラムまたはプロシージャー内で渡されなかった パラメーターがアクセスされると、予測できない結果を招きます。
OPTIONS(*OMIT) を指定した場合には、そのパラメーターに値 *OMIT を使用する ことができます。 *OMIT を使用できるのは、CONST パラメーターと、参照によって渡されるパラメーターの場合だけです。省略されるパラメーターの詳細については、「WebSphere Development Studio: ILE RPG プログラマーの手引き」のプログラムおよび プロシージャーの呼び出しに関する章を参照してください。
OPTIONS(*VARSIZE) が有効なのは、パラメーターが文字、図形、または UCS-2 データ・タイプの参照、または任意のタイプの配列を表す参照によって渡される場合だけです。
OPTIONS(*VARSIZE) を指定した場合には、渡されるパラメーターはプロトタイプ に定義された長さより短いか、または長い可能性があります。 渡された量だけの データにアクセスするのは、呼び出し先プログラムまたはサブプロシージャーの 責任になります。 渡すデータの量を伝えるために、長さを含む別の パラメーターを渡すか、または、サブプロシージャー用の操作記述子を使用 することができます。 可変長フィールドの場合、渡されたパラメーターの現在の 長さを決定するために %LEN 組み込み関数を使用することができます。
固定長フィールドの場合に、OPTIONS(*VARSIZE) を省略するときは、 少なくとも プロトタイプによって要求されている量の データを渡す必要があります。可変長フィールドの場合、パラメーターは、 定義で宣言された最大長を持っていなければなりません。
値または定数参照によって渡される基底ポインター・パラメーター に OPTIONS(*STRING) を指定する場合、ポインターまたは文字式のいずれかを 渡してもかまいません。 文字式を渡す場合、後ろに ヌル文字終了記号 (x'00') が 付いている文字式の値を含んだ一時値が作成 されます。 この一時値のアドレスは、呼び出されるプログラムまたはプロシージャーに 渡されます。
プロトタイプ内の CONST パラメーターまたは VALUE パラメーター に OPTIONS(*RIGHTADJ) を指定すると、文字、図形、または UCS-2 パラメーター値 は右寄せされます。 このキーワードは、プロシージャー・プロトタイプ内の可変長パラメーターに は使用できません。 可変長値は、対応のパラメーターが OPTIONS(*RIGHTADJ) を指定して 定義されているプロシージャー呼び出し上で、パラメーターとして 渡すことができます。
文字、UCS-2、またはグラフィック・タイプの CONST または VALUE パラメーターに OPTIONS(*TRIM) を 指定した場合、渡されたパラメーターは、先行および後書きブランクなしで一時ファイルにコピーされます。 このパラメーターが可変長パラメーターでない場合、トリミングされた値にはブランクが 埋め込まれます (OPTIONS(*RIGHTADJ) が指定されている場合には左側に、 それ以外の場合には右側に埋め込まれます)。 そして、この一時ファイルがオリジナル・パラメーターの代わりに渡されます。 OPTIONS(*TRIM) を指定すると、パラメーターは、 プロシージャーに対するそれぞれの呼び出しで %TRIM がコーディングされた場合とまったく同様に渡されます。
ポインター・タイプの CONST または VALUE パラメーターに OPTIONS(*STRING : *TRIM) を 指定した場合、文字パラメーターまたはポインター・パラメーターの %STR が、先行または後書きブランクなしで一時ファイルにコピーされ、 ヌル終止符が一時ファイルに追加されて、その一時ファイルのアドレスが渡されます。
OPTIONS(*NULLIND) がパラメーターに指定されている場合 は、ヌル・バイト・マップがそのパラメーター付きで渡されます。 これにより、着呼側プロシージャーは、発呼者パラメーターのヌル・バイ ト・マップに直接アクセスできます。OPTIONS(*NULLIND) の以下の規則に注意してください。
複数のオプションを指定することができます。 たとえば、任意指定パラメーターをプロトタイプの指示より短くすることができ ることを指定するためには、OPTIONS(*VARSIZE : *NOPASS) とコーディングされ ます。
次の例は、パラメーターがオプションであることを示すため に OPTIONS(*NOPASS) を使用するプロトタイプおよびプロシージャー をコーディングする方法を示しています。
* The following prototype describes a procedure that expects * either one or two parameters. D FormatAddress PR 45A D City 20A CONST D Province 20A CONST OPTIONS(*NOPASS) * The first call to FormatAddress only passes one parameter. The * second call passes both parameters. C EVAL A = FormatAddress('North York') C EVAL A = FormatAddress('Victoria' : 'B.C.') C RETURN *---------------------------------------------------------------- * FormatAddress: * This procedure must check the number of parameters since the * second was defined with OPTIONS(*NOPASS). * It should only use the second parameter if it was passed. *---------------------------------------------------------------- P FormatAddress B D FormatAddress PI 45A D City 20A CONST D ProvParm 20A CONST OPTIONS(*NOPASS) D Province S 20A INZ('Ontario') * Set the local variable Province to the value of the second * parameter if it was passed. Otherwise let it default to * 'Ontario' as it was initialized. C IF %PARMS > 1 C EVAL Province = ProvParm C ENDIF * Return the city and province in the form City, Province * for example 'North York, Ontario' C RETURN %TRIMR(City) + ',' + Province P FormatAddress E
次の例は、特殊値の *OMIT がパラメーターとして渡される可能性が あることを示すために、OPTIONS(*OMIT) を使用してプロトタイプおよび プロシージャーをコーディングする方法を示しています。
FQSYSPRT O F 10 PRINTER USROPN * The following prototype describes a procedure that allows * the special value *OMIT to be passed as a parameter. * If the parameter is passed, it is set to '1' if an error * occurred, and '0' otherwise. D OpenFile PR D Error 1A OPTIONS(*OMIT) C SETOFF 10 * The first call to OpenFile assumes that no error will occur, * so it does not bother with the error code and passes *OMIT. C CALLP OpenFile(*OMIT) * The second call to OpenFile passes an indicator so that * it can check whether an error occurred. C CALLP OpenFile(*IN10) C IF *IN10 C ... an error occurred C ENDIF C RETURN *---------------------------------------------------------------- * OpenFile * This procedure must check the number of parameters since the * second was defined with OPTIONS(*OMIT). * It should only use the second parameter if it was passed. *---------------------------------------------------------------- P OpenFile B D OpenFile PI D Error 1A OPTIONS(*OMIT) D SaveIn01 S 1A * Save the current value of indicator 01 in case it is being * used elsewhere. C EVAL SaveIn01 = *IN01 * Open the file. *IN01 will indicate if an error occurs. C OPEN QSYSPRT 01 * If the Error parameter was passed, update it with the indicator C IF %ADDR(Error) <> *NULL C EVAL Error = *IN01 C ENDIF * Restore *IN01 to its original value. C EVAL *IN01 = SaveIn01 P OpenFile E
次の例は、OPTIONS(*VARSIZE) を使用して、可変長パラメーターを使用可能にする プロトタイプおよびプロシージャーをコーディングする方法を示しています。
* The following prototype describes a procedure that allows * both a variable-length array and a variable-length character * field to be passed. Other parameters indicate the lengths. D Search PR 5U 0 D SearchIn 50A OPTIONS(*VARSIZE) D DIM(100) CONST D ArrayLen 5U 0 VALUE D ArrayDim 5U 0 VALUE D SearchFor 50A OPTIONS(*VARSIZE) CONST D FieldLen 5U 0 VALUE D Arr1 S 1A DIM(7) CTDATA PERRCD(7) D Arr2 S 10A DIM(3) CTDATA D Elem S 5U 0 * Call Search to search an array of 7 elements of length 1 with * a search argument of length 1. Since the '*' is in the 5th * element of the array, Elem will have the value 5. C EVAL Elem = Search(Arr1 : C %SIZE(Arr1) : %ELEM(Arr1) : C '*' : 1) * Call Search to search an array of 3 elements of length 10 with * a search argument of length 4. Since 'Pink' is not in the * array, Elem will have the value 0. C EVAL Elem = Search(Arr2 : C %SIZE(Arr2) : %ELEM(Arr2) : C 'Pink' : 4) C RETURN
*------------------------------------------------------------ * Search: * Searches for SearchFor in the array SearchIn. Returns * the element where the value is found, or 0 if not found. * The character parameters can be of any length or * dimension since OPTIONS(*VARSIZE) is specified for both. *------------------------------------------------------------ P Search B D Search PI 5U 0 D SearchIn 50A OPTIONS(*VARSIZE) D DIM(100) CONST D ArrayLen 5U 0 VALUE D ArrayDim 5U 0 VALUE D SearchFor 50A OPTIONS(*VARSIZE) CONST D FieldLen 5U 0 VALUE D I S 5U 0 * Check each element of the array to see if it the same * as the SearchFor. Use the dimension that was passed as * a parameter rather than the declared dimension. Use * %SUBST with the length parameter since the parameters may * not have the declared length. C 1 DO ArrayDim I 5 0 * If this element matches SearchFor, return the index. C IF %SUBST(SearchIn(I) : 1 : ArrayLen) C = %SUBST(SearchFor : 1 : FieldLen) C RETURN I C ENDIF C ENDDO * No matching element was found. C RETURN 0 P Search E Compile-time data section: **CTDATA ARR1 A2$@*jM **CTDATA ARR2 Red Blue Yellow
次の例は、ヌル文字で終了するストリング・パラメーターを使用する プロトタイプおよびプロシージャーをコーディングするため に OPTIONS(*STRING) を使用する方法を示しています。
* The following prototype describes a procedure that expects * a null-terminated string parameter. It returns the length * of the string. D StringLen PR 5U 0 D Pointer * VALUE OPTIONS(*STRING) D P S * D Len S 5U 0 * Call StringLen with a character literal. The result will be * 4 since the literal is 4 bytes long. C EVAL Len = StringLen('abcd') * Call StringLen with a pointer to a string. Use ALLOC to get * storage for the pointer, and use %STR to initialize the storage * to 'My string¬' where '¬' represents the null-termination * character x'00'. * The result will be 9 which is the length of 'My string'. C ALLOC 25 P C EVAL %STR(P:25) = 'My string' C EVAL Len = StringLen(P) * Free the storage. C DEALLOC P C RETURN *------------------------------------------------------------ * StringLen: * Returns the length of the string that the parameter is * pointing to. *------------------------------------------------------------ P StringLen B D StringLen PI 5U 0 D Pointer * VALUE OPTIONS(*STRING) C RETURN %LEN(%STR(Pointer)) P StringLen E
* The following prototype describes a procedure that expects * these parameters: * 1. trimLeftAdj - a fixed length parameter with the * non-blank data left-adjusted * 2. leftAdj - a fixed length parameter with the * value left-adjusted (possibly with * leading blanks) * 3. trimRightAdj - a fixed length parameter with the * non-blank data right-adjusted * 4. rightAdj - a fixed length parameter with the * value right-adjusted (possibly with * trailing blanks) * 5. trimVar - a varying parameter with no leading * or trailing blanks * 6. var - a varying parameter, possibly with * leading or trailing blanks D trimProc PR D trimLeftAdj 10a const options(*trim) D leftAdj 10a const D trimRightAdj 10a value options(*rightadj : *trim) D rightAdj 10a value options(*rightadj) D trimVar 10a const varying options(*trim) D var 10a value varying * The following prototype describes a procedure that expects * these parameters: * 1. trimString - a pointer to a null-terminated string * with no leading or trailing blanks * 2. string - a pointer to a null-terminated string, * possibly with leading or trailing blanks
D trimStringProc PR D trimString * value options(*string : *trim) D string * value options(*string) D ptr s * /free // trimProc is called with the same value passed // for every parameter // // The called procedure receives the following parameters // trimLeftAdj 'abc ' // leftAdj ' abc ' // trimRightAdj ' abc' // rightAdj ' abc ' // trimVar 'abc' // var ' abc ' callp trimProc (' abc ' : ' abc ' : ' abc ' : ' abc ' : ' abc ' : ' abc ' ); // trimStringProc is called with the same value passed // for both parameters // // The called procedure receives the following parameters, // where ¬ represents x'00' // trimstring pointer to 'abc¬' // string pointer to ' abc ¬' callp trimStringProc (' abc ' : ' abc '); // trimStringProc is called with the same pointer passed // to both parameters // // The called procedure receives the following parameters, // where ¬ represents x'00' // trimstring pointer to 'xyz¬' // string pointer to ' xyz ¬' ptr = %alloc (6); %str(ptr : 6) = ' xyz '; callp trimStringProc (ptr : ptr);
*----------------------------------- * DDS for file NULLFILE *----------------------------------- A R TESTREC A NULL1 10A ALWNULL A NOTNULL2 10A A NULL3 10A ALWNULL *----------------------------------- * Calling procedure *----------------------------------- * The externally-described data structure DS, and the * data structure DS2 defined LIKEDS(ds) have * null-capable fields NULL1 and NULL3. D ds E DS EXTNAME(nullFile) D ds2 DS LIKEDS(ds) * Procedure PROC specifies OPTIONS(*NULLIND) for all its * parameters. When the procedure is called, the * null-byte maps of the calling procedure's parameters * will be passed to the called procedure allowing the * called procedure to use %NULLIND(parmname) to access the * null-byte map. D proc PR D parm LIKEDS(ds) D OPTIONS(*NULLIND) D parm2 10A OPTIONS(*NULLIND) D parm3 10A OPTIONS(*NULLIND) CONST /free // The calling procedure sets some values // in the parameters and their null indicators %nullind(ds.null1) = *on; ds.notnull2 = 'abcde'; ds.null3 = 'fghij'; %nullind(ds.null3) = *off; ds2.null1 = 'abcde'; %nullind(ds2.null1) = *on; %nullind(ds3.null3) = *off; // The procedure is called (see the code for // the procedure below proc (ds : ds2.null1 : ds2.null3); // After "proc" returns, the calling procedure // displays some results showing that the // called procedure changed the values of // the calling procedure's parameters and // their null-indicators dsply (%nullind(ds.null1)); // displays '0' dsply ds2.null2; // displays 'newval' dsply (%nullind(ds2.null2)); // displays '0' /end-free
*----------------------------------- * Called procedure PROC *----------------------------------- P B D proc PI D parm LIKEDS(ds) D OPTIONS(*NULLIND) D parm2 10A OPTIONS(*NULLIND) D parm3 10A OPTIONS(*NULLIND) CONST /free if %NULLIND(parm.null1); // This code will be executed because the // caller set on the null indicator for // subfield NULL1 of the parameter DS endif; if %NULLIND(parm3); // PARM3 is defined as null-capable since it was // defined with OPTIONS(*NULLIND). // This code will not be executed, because the // caller set off the null-indicator for the parameter endif; // Change some data values and null-indicator values // The calling procedure will see the updated values. parm2 = 'newvalue'; %NULLIND(parm2) = *OFF; %NULLIND(parm.null1) = *OFF; parm.null1 = 'newval'; return; /end-free P E
(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.