OPTIONS(*NOPASS *OMIT *VARSIZE *STRING *TRIM *RIGHTADJ *NULLIND)

OPTIONS キーワードは、次のようなオプションを渡す 1 つまたは複数のパラメー ターを指定するために使用されます。

OPTIONS(*NOPASS) を定義仕様書に指定した場合には、呼び出し時にパラメーターを渡 す必要はありません。 この指定より後のすべてのパラメーターにも、*NOPASS の指定が必要です。 プログラムまたはプロシージャーにパラメーターが渡されないと、呼び出されたプログラムまたはプロシージャーは、単に、パラメーター・リストにそのパラメーターが含まれていないものとして機能します。 呼び出されたプログラムまたはプロシージャー内で渡されなかった パラメーターがアクセスされると、予測できない結果を招きます。

OPTIONS(*OMIT) を指定した場合には、そのパラメーターに値 *OMIT を使用する ことができます。 *OMIT を使用できるのは、CONST パラメーターと、参照によって渡されるパラメーターの場合だけです。省略されるパラメーターの詳細については、「WebSphere Development Studio: ILE RPG プログラマーの手引き」のプログラムおよび プロシージャーの呼び出しに関する章を参照してください。

OPTIONS(*VARSIZE) が有効なのは、パラメーターが文字、図形、または UCS-2 データ・タイプの参照、または任意のタイプの配列を表す参照によって渡される場合だけです。

OPTIONS(*VARSIZE) を指定した場合には、渡されるパラメーターはプロトタイプ に定義された長さより短いか、または長い可能性があります。 渡された量だけの データにアクセスするのは、呼び出し先プログラムまたはサブプロシージャーの 責任になります。 渡すデータの量を伝えるために、長さを含む別の パラメーターを渡すか、または、サブプロシージャー用の操作記述子を使用 することができます。 可変長フィールドの場合、渡されたパラメーターの現在の 長さを決定するために %LEN 組み込み関数を使用することができます。

固定長フィールドの場合に、OPTIONS(*VARSIZE) を省略するときは、 少なくとも プロトタイプによって要求されている量の データを渡す必要があります。可変長フィールドの場合、パラメーターは、 定義で宣言された最大長を持っていなければなりません。

注:
オプション *NOPASS、*OMIT、および *VARSIZE を渡すパラメーターの場合、 そのプロシージャーのプログラマーは、これらのオプションが確実に処理されるようにする必要があります。 たとえば、OPTIONS(*NOPASS) がコーディングされていて、パラメーターを 渡すようにした場合、プロシージャーは、そのパラメーターにアクセスする 前にそれが渡されていることをチェックする必要があります。 コンパイラーは、これについては一切チェックしません。

値または定数参照によって渡される基底ポインター・パラメーター に 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) を使用するプロトタイプおよびプロシージャー をコーディングする方法を示しています。

図 123. パラメーターがオプションであることを示すための 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) を使用してプロトタイプおよび プロシージャーをコーディングする方法を示しています。

図 124. 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) を使用して、可変長パラメーターを使用可能にする プロトタイプおよびプロシージャーをコーディングする方法を示しています。

図 125. 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) を使用する方法を示しています。

図 126. 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
図 127. OPTIONS(*TRIM) の使用
* 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);
図 128. OPTIONS(*NULLIND) の使用
 *-----------------------------------
 * 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