OPTIONS(*NOPASS *OMIT *VARSIZE *STRING *TRIM *RIGHTADJ *NULLIND)
- Whether a parameter must be passed
- Whether the special value *OMIT can be passed for the parameter passed by reference.
- Whether a parameter that is passed by reference can be shorter in length than is specified in the prototype.
- Whether the called program or procedure is expecting a pointer to a null-terminated string, allowing you to specify a character expression as the passed parameter.
- Whether the parameter should be trimmed of blanks before being passed.
- Whether the parameter value should be right-adjusted in the passed parameter.
- Whether the null-byte-map should be passed with the parameter.
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 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.
For parameters passed by reference, the address of the passed parameter is passed on the call except when a temporary is used for a read-only reference parameter; in that case, the address of the temporary is passed on the call. For more information about the use of a temporary with a read-only reference parameter, see CONST{(constant)}.
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.
- ALWNULL(*USRCTL) must be in effect.
- OPTIONS(*NULLIND) is not valid for parameters passed by value.
- The only other options that can be specified with OPTIONS(*NULLIND) are *NOPASS and *OMIT.
- Only variables may be passed as the parameter when OPTIONS(*NULLIND) is specified, and the variable must be an exact match even when CONST is specified.
- If the parameter is a data structure, the passed parameter must be defined with the same parent LIKEDS or LIKEREC as the prototyped parameter. Furthermore, the null-capability of the prototyped parameter and passed parameter must match exactly.
- A prototyped data structure parameter can have OPTIONS(*NULLIND) specified whether or not there are any null-capable subfields.
- If a non-data-structure prototyped parameter is defined with OPTIONS(*NULLIND), the parameter in the procedure interface is defined as null-capable.
- See Rational Development Studio for i: ILE RPG Programmer's Guide for information about using OPTIONS(*NULLIND) when the calling procedure or called procedure is not written using ILE RPG.
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