The OPTIONS keyword is used to specify one or more parameter passing options:
When OPTIONS(*NOPASS) is specified on a definition specification, the parameter does not have to be passed on the call. Any parameters following that specification must also have *NOPASS specified. When the parameter is not passed to a program or procedure, the called program or procedure will simply function as if the parameter list did not include that parameter. If the unpassed parameter is accessed in the called program or procedure, unpredictable results will occur.
When OPTIONS(*OMIT) is specified, then the value *OMIT is allowed for that parameter. *OMIT is only allowed for CONST parameters and parameters which are passed by reference. For more information on omitted parameters, see the chapter on calling programs and procedures in IBM Rational Development Studio for i: ILE RPG Programmer's Guide.
OPTIONS(*VARSIZE) is valid only for parameters passed by reference that have a character, graphic, or UCS-2 data type, or that represent an array of any type.
When OPTIONS(*VARSIZE) is specified, the passed parameter may be shorter or longer in length than is defined in the prototype. It is then up to the called program or subprocedure to ensure that it accesses only as much data as was passed. To communicate the amount of data passed, you can either pass an extra parameter containing the length, or use operational descriptors for the subprocedure. For variable-length fields, you can use the %LEN built-in function to determine the current length of the passed parameter.
When OPTIONS(*VARSIZE) is omitted for fixed-length fields, you must pass at least as much data as is required by the prototype; for variable-length fields, the parameter must have the same declared maximum length as indicated on the definition.
When OPTIONS(*STRING) is specified for a basing pointer parameter passed by value or by constant-reference, you may either pass a pointer or a character expression. If you pass a character expression, a temporary value will be created containing the value of the character expression followed by a null-terminator (x'00'). The address of this temporary value will be passed to the called program or procedure.
When OPTIONS(*RIGHTADJ) is specified for a CONST or VALUE parameter in a prototype, the character, graphic, or UCS-2 parameter value is right adjusted. This keyword is not allowed for a varying length parameter within a procedure prototype. Varying length values may be passed as parameters on a procedure call where the corresponding parameter is defined with OPTIONS(*RIGHTADJ).
When OPTIONS(*TRIM) is specified for a CONST or VALUE parameter of type character, UCS-2 or graphic, the passed parameter is copied without leading and trailing blanks to a temporary. If the parameter is not a varying length parameter, the trimmed value is padded with blanks (on the left if OPTIONS(*RIGHTADJ) is specified, otherwise on the right). Then the temporary is passed instead of the original parameter. Specifying OPTIONS(*TRIM) causes the parameter to be passed exactly as though %TRIM were coded on every call to the procedure.
When OPTIONS(*STRING : *TRIM) is specified for a CONST or VALUE parameter of type pointer, the character parameter or %STR of the pointer parameter is copied without leading or trailing blanks to a temporary, a null-terminator is added to the temporary and the address of the temporary is passed.
When OPTIONS(*NULLIND) is specified for a parameter, the null-byte map is passed with the parameter, giving the called procedure direct access to the null-byte map of the caller's parameter. Note the following rules for OPTIONS(*NULLIND).
You can specify more than one option. For example, to specify that an optional parameter can be shorter than the prototype indicates, you would code OPTIONS(*VARSIZE : *NOPASS).
The following example shows how to code a prototype and procedure that use OPTIONS(*NOPASS) to indicate that a parameter is optional.
* 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 EThe following example shows how to code a prototype and procedure using OPTIONS(*OMIT) to indicate that the special value *OMIT may be passed as a parameter.
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 EThe following example shows how to code a prototype and procedure allowing variable-length parameters, using 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
YellowThe following example shows how to use OPTIONS(*STRING) to code a prototype and procedure that use a null-terminated string parameter.
* 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