/**
@class Valence_RPG_Toolkit.vvIn
vvIn procedures are used to retrieve post/get variables from the browser so they can be used in RPG programs as variables, arrays, or data structures.
For example, if the JavaScript below is executed in the browser,
Ext.Ajax.request({
url: 'vvcall.pgm',
params: {
pgm: 'RPG100',
action: 'getRec',
cusno: currentRecord.get('CUSNO')
}
Valence will use the 'pgm' to call your RPG program called 'RPG100' where the variables 'action'
and 'cusno' can be retrieved into variables as follows:
d action s 20a
d customer s 6s 0
/copy qcpylesrc,vvDspec
/free
action = vvIn_char('action');
customer = vvIn_num('cusno');
/end-free
*/
/**
@method _array
Retrieves post/get variables from the browser and places their values into a single field RPG array. The array must be defined as character (see Example 2 below for how to handle numeric data).<br>
<i>Note: to retrieve browser data into a <b>data structure array</b> use [vvIn_json](#!/api/VVSRVPGM.vvIn-method-_json).</i>
@param {50a, const varying (required)} variableName A character expression representing the name of the variable sent in from the browser.
@param {*pointer, value (required)} pointerToArray A pointer address to an internal character array that will hold the data retrieved from the browser.
@param {10i0, const (required)} arraySize The total size of the array.
@param {10i0, const (required)} elementSize The size of a single array element.
@param {n, const (optional)} isVarying Set to *on if array field is varying. If set to *off or not passed, array field is assumed to be fixed size.
@return {10i0} NumberOfElements Returns a numeric value representing the number of elements added to the array.
##RPG Examples
###Example 1
// suppose the front end has defined an array of items in the JavaScript as
// follows:
// var Items = new Array('');
// Items[0]='firstItem';
// Items[1]='secondItem';
// Items[2]='thirdItem';
// the browser has posted the array as "items" without any particular index...
// in order to pull the array of items into our program, we must create an
// an array to hold them...
d itemArray s 15a dim(500)
d itemCount s 3 0
d ii s 3 0
/copy qcpylesrc,vvDspec
/free
itemCount = vvIn_array('items'
:%addr(itemArray)
:%size(itemArray:*all)
:%size(itemArray));
// now the data will be available in the itemArray variable...
if itemCount>0;
for ii=1 to itemCount;
// do something...
endfor;
endif;
/end-free
###Example 2
// the browser has posted an array of order numbers, the variable name is "orders"...
// create an array of orders...
// NOTE: the array must be character
d orderArray s 6a dim(500)
d orderCount s 3 0
d ii s 3 0
d orderNumber s 6 0
/copy qcpylesrc,vvDspec
/free
orderCount = vvIn_array('orders'
:%addr(orderArray)
:%size(orderArray:*all)
:%size(orderArray));
// now the data will be available in the orderArray variable...
if orderCount>0;
for ii=1 to orderCount;
orderNumber = %int(orderArray(ii));
endfor;
endif;
/end-free
*/
/**
@method _boolean
Retrieves post/get variables from the browser. The value is returned back as boolean.
@param {50a, const varying (required)} variableName A character expression representing the name of the variable sent in from the browser. The browser values returned as true/on are: true, *true, *yes, y, yes, on, and 1, all other values are evaluated as false/off. Browser values can be upper or lower case.
@return {n}
## RPG Example
d isActive s n
/copy qcpylesrc,vvDspec
/free
isActive = vvIn_boolean('active');
if isActive;
// code to execute on active.
endif;
/end-free
*/
/**
@method _char
Retrieves post/get variables from the browser. The value is returned as a character string.
@param {50a, const varying (required)} variableName A character expression representing the name of the variable sent in
from the browser. A special value of `*ALL` will return the entire input buffer.
@param {1p0, const (optional)} formatOption Optionally adjusts the data being returned from the browser. The VVDSPEC copy source member contains two formatting constants:
- `TOUPPER` Format the returned character string to all uppercase
- `TOLOWER` Format the returned character string to all lowercase
@return {65535a varying} characterValue
## RPG Example
d action s 20a
/copy qcpylesrc,vvDspec
/free
// the browser has sent in a variable named "action"
// retrieve the value and place it in a variable named "action"
action = vvIn_char('action');
// suppose you wanted to set the variable to uppercase or lowercase...
action = vvIn_char('action':TOUPPER);
action = vvIn_char('action':TOLOWER);
/end-free
*/
/**
@method _cookie
Retrieves the variable name from the HTTP_COOKIE environment variable. The value is returned as a character string.
@param {50a, const varying (required)} variableName A character expression representing the name of the variable sent in the cookie.
@param {1p0, const (optional)} formatOption Optionally adjusts the data being returned from the browser. The VVDSPEC copy source member contains two formatting constants:
- `TOUPPER` Format the returned character string to all uppercase
- `TOLOWER` Format the returned character string to all lowercase
@return {65535a varying} characterValue
## RPG Example
d lastItem s 20a
/copy qcpylesrc,vvDspec
/free
// the browser has sent in cookie with the name of "lastitem"
// so retrieve the value and place it in a variable named "lastItem"...
lastItem = vvIn_cookie('lastItem');
/end-free
*/
/**
@method _date
Retrieves post/get variables from the browser into *ISO date format.
@param {50a, const varying (required)} variableName A character expression representing the name of the variable sent in from the browser
@param {4a, const varying (optional)} dateFormat A character expression representing the expected date format of the variable passed in from the browser:
- `*MDY`
- `*DMY`
- `*YMD`
- `*JUL`
- `*ISO`
- `*USA`
- `*EUR`
- `*JIS`
If no date format is specified, vvIn_date will try converting the browser date field from all
the formats listed above, in the order shown, until a successful conversion is made.
@return {date (*ISO format)} dateValue
## RPG Example
d orderDate s d datfmt(*iso)
/copy qcpylesrc,vvDspec
/free
// the browser has sent in a variable named "orderDate",
// retrieve the value and place it in the orderDate variable.
// since we are not quite sure of the date format being sent in, omit the
// optional date format parameter...
orderDate = vvIn_date('orderDate');
// or, if we know the date format of the date being sent in from the browser...
orderDate = vvIn_date('orderDate':'*MDY');
/end-free
*/
/**
@method _ds
Populate a data structure with post/get variables sent from the browser. For each field name
within the data structure, a corresponding post/get variable will be retrieved based on the
name of the field.
@param {DS (required)} vvIn The vvIn qualified data structure is automatically included as part
of the VVDSPEC copy source member. The subfields pertinent to vvIn_DS are:
- `object` The name of the object that the data structure pointer (parameter 2) is based on.
- `library` The library corresponding to the object. If not specified, *LIBL will be assumed.
- `recordFormat` The record format of the object. If not specified, *FIRST will be assumed.
- `prefix` If non blanks, this value will serve as a prefix to each field name before attempting to retrieve the post/get variable from the browser.
- `suffix` If non blanks, this value will serve as a suffix to each field name before attempting to retrieve the post/get variable from the browser.
- `longSqlNames` Set to "Y" to extract long SQL field names.
@param {*pointer, value (required)} pointerToDataStructure Pointer to the data structure to be populated
@return {n} Returns *on if successful; *off if not.
## RPG Examples
###Example 1
d post_Parms e ds extname(CUSTMASTER) qualified inz
/copy qcpylesrc,vvDspec
/free
// the browser has posted variables for adding a new customer record...
// the variable names are as follows:
// - CUSNUMBER
// - CUSNAME
// - CUSADDR1
// - CUSADDR2
// - CUSADDR3
// - CUSCITY
// - CUSSTATE
// - CUSZIP
// the CUSTMASTER file has the same field names as the variables referenced
// above...thus, we created an external data structure (above) named post_Parms
// based off of the CUSTMASTER file
//
vvIn.object = 'CUSTMASTER';
vvIn_DS(vvIn:%addr(post_Parms));
// the post_Parms data structure will now be populated with the values
// sent in from the browser...
//
chain (post_Parms.CUSNUMBER) custMaster;
if %found(custMaster);
//do something...
endif;
/end-free
###Example 2 - using a prefix
d post_Parms e ds extname(CUSTMASTER) qualified inz
d post_Parms e ds extname(CUSTMASTER) qualified inz
/copy qcpylesrc,vvDspec
/free
// the browser has posted variables for adding a new customer record...
// the variable names are as follows:
// - add_CUSNUMBER
// - add_CUSNAME
// - add_CUSADDR1
// - add_CUSADDR2
// - add_CUSADDR3
// - add_CUSCITY
// - add_CUSSTATE
// - add_CUSZIP
// the CUSTMASTER file has the same field names as the variables referenced
// above (except for the "add_" portion)...thus, we created an external data
// structure (above) named post_Parms based off of the CUSTMASTER file
//
vvIn.object = 'CUSTMASTER';
vvIn.prefix = 'add_';
vvIn_DS(vvIn:%addr(post_Parms));
// the post_Parms data structure will now be populated with the values
// sent in from the browser...
//
chain (post_Parms.CUSNUMBER) custMaster;
if %found(custMaster);
//do something...
endif;
/end-free
*/
/**
@method _file
Receive a file sent from the browser and store it to the IFS. Returns a pointer to the file.
@param {DS (required)} vvIn The vvIn qualified data structure is automatically included as part
of the VVDSPEC copy source member. The subfields pertinent to vvIn_file are:
- `path` The full path to the IFS directory to store the file.
- `fileName` The name of the file when saved to the IFS. Note: include the file extension. If
left blank, the filename will be set to the name of the upload file from the user PC.
- `ccsid` The numeric CCSID of the file being uploaded. Defaults to 819 if not specified.
@param {1024a, const varying (optional)} successText On a successful upload, the message text to be returned to the
browser. If this parameter is not passed then a basic "success:true" type message is returned to the browser; If a value
of *NULL is passed then no message will be sent, leaving it up to your RPG program to send a response to the browser.
@return {10i0} returnLength Size of the file (in bytes)
## RPG Example
NOTE: this program must run within the VALENCE activation group
d orderDate s d datfmt(*iso)
d message s 256a
/copy qcpylesrc,vvDspec
/free
// ifs directory to save the file...
//
vvIn.path = '/user/Joe/uploads/';
// set a custom success message...
//
message = 'Your file has been uploaded to ' + %trim(vvIn.path);
// save the file...
//
vvIn_file(vvIn : message);
// suppose you have a purpose to access the file in memory...
// change the call to vvIn_file as follows...
//
filePtr = vvIn_file(vvIn : message);
// filePtr is now pointed to the first byte of the file...
// vvIn.returnLength represents the total length of the file...
/end-free
*/
/**
@method _json
Retrieves JSON-formatted post/get variables from the browser into an RPG array.
@param {DS (required)} vvIn The vvIn qualified data structure is automatically included as part of the VVDSPEC copy source member. The subfields pertinent to vvIn_JSON are:
- `variableName` The name of the post/get variable sent in from the browser.
- `object` The name of the object that the array pointer (parameter 2) is based on. **NOTE: If an object
is not passed, then "fieldName" must be set.**
- `library` (optional) The library corresponding to the object. If not specified, \*LIBL will be assumed.
- `recordFormat` (optional) The record format of the object. If not specified, \*FIRST will be assumed.
- `fieldName` - The name of the field in the JSON response to extract. NOTE: This is ignored if an object is passed.
- `elementSize` - The total size (in bytes) of the RPG array associated with the pointer (pointerToArray). NOTE: This value is ignored if an object is passed.
- `totalSize` - The total size (in bytes) of the RPG array associated with the pointer (pointerToArray). Should be a multiple of elementSize (if specified).
- `skipOutputIndex` - (Optional) The number of array elements to skip before populating. Thus, leaving the first skipOutputIndex number of elements intact.
- `longSqlNames` - (Optional) Set to "Y" to extract long SQL field names.
- `lowercase` - (Optional) Set to "Y" or "1" to lowercase the fieldnames of the object passed in. This is only if passing in an object (vvIn.object) and the front-end posted the object fieldnames in lowercase.
@param {*, value (required)} pointerToArray Pointer to the array
@return {10i0} numberOfElements total elements added to the array
## RPG Examples
###Example 1 - Using an object
Suppose the browser has posted a variable named "records", it is a JSON string of customer records...
[
{"CUSNUMBER":1,"CUSNAME":"ACME","CUSCITY":"Toledo","CUSSTATE":"OH"},
{"CUSNUMBER":2,"CUSNAME":"CNX","CUSCITY":"Chicago","CUSSTATE":"IL"},
{"CUSNUMBER":3,"CUSNAME":"A-1","CUSCITY":"Orlando","CUSSTATE":"FL"}
]
then the following RPG code will populate the data structure
d orderDate s d datfmt(*iso)
d cusRecords e ds extname(CUSTMASTER) inz
qualified dim(500)
d numElements s 3 0
d ii s 3 0
/copy qcpylesrc,vvDspec
/free
vvIn.variableName = 'records';
vvIn.object = 'CUSTMASTER';
vvIn.totalSize = %size(cusRecords:*all);
numElements = vvIn_JSON(vvIn:%addr(cusRecords));
// the cusRecords array will now be populated with the values from the JSON
// string with numElements representative of the number of elements populated...
//
for ii=1 to numElements;
chain(n) (cusRecords(ii).CUSNUMBER) fileXXX;
if %found(fileXXX);
fieldA = cusRecords(ii).CUSNAME;
endif;
endfor;
/end-free
###Example 2 - Using a single field name
Suppose the browser has posted a variable named "records", it is a JSON string of customer records...
[
{"CUSNUMBER":1,"CUSNAME":"ACME","CUSCITY":"Toledo","CUSSTATE":"OH"},
{"CUSNUMBER":2,"CUSNAME":"CNX","CUSCITY":"Chicago","CUSSTATE":"IL"},
{"CUSNUMBER":3,"CUSNAME":"A-1","CUSCITY":"Orlando","CUSSTATE":"FL"}
]
We want to extract all of the customer names out of this json string... the values will be
extracted into the cusNames array.
d cusNames s 30a dim(500)
d numElements s 3 0
d ii s 3 0
/copy qcpylesrc,vvDspec
/free
vvIn.variableName = 'records';
vvIn.fieldName = 'CUSNAME';
vvIn.totalSize = %size(cusNames:*all);
vvIn.elementSize = %size(cusNames);
numElements = vvIn_JSON(vvIn:%addr(cusNames));
// the cusNames array will now be populated with all of the "CUSNAME" values
// from the JSON string with numElements representative of the number of
// elements populated...
//
for ii=1 to numElements;
chain(n) (cusNames(ii)) fileXYZ;
if %found(fileXYZ);
// do something...
endif;
endfor;
/end-free
*/
/**
@method _num
Retrieves post/get variables from the browser and sets the RPG numeric variable.
@param {50a, const varying (required)} variableName A character expression representing the name of the variable sent in from the browser
@return {30p9} numericValue The number sent from the browser
##RPG Example
d orderNum s 6 0
/copy qcpylesrc,vvDspec
/free
// the browser has sent in a variable named "orderNumber",
// retrieve the value and place it in the orderNum variable...
//
orderNum = vvIn_num('orderNumber');
/end-free
*/
/**
@method _time
Retrieves post/get variables from the browser and returns a RPG time variable.
@param {50a, const varying (required)} variableName A character expression representing the name of the variable sent in from the browser
@param {4a, const varying (optional)} timeFormat A character expression representing the expected time format of the variable passed in from the browser. This value cooresponds to the valid RPG time formats:
<pre>
<table border=1 cellspacing=0 cellpadding=3px width="100%"
style='width:95.0%;margin-left:3pt;border-collapse:collapse;border:none;>
<tr valign=top style='border:solid black 1.0pt;'>
<td>Format </td><td>Description </td><td>Format </td><td>Valid Separators</td><td>Example </td> </tr>
<tr>
<td>*HMS </td><td>Hours:Minutes:Seconds </td><td>hh:mm:ss </td><td> :.,& </td><td>04:25:15</td> </tr>
</tr><tr>
<td>*ISO </td><td>International Standards Organization </td><td>hh.mm.ss </td><td> . </td><td>04.25.15</td> </tr>
</tr><tr>
<td>*USA </td><td>IBM USA Standard. <br>AM and PM can be any mix of upper and lower case. </td><td>hh:mm PM </td><td> : </td><td>04:25 PM</td> </tr>
</tr><tr>
<td>*EUR </td><td>IBM European Standard </td><td>hh.mm.ss </td><td> . </td><td>04.25.15</td> </tr>
</tr><tr>
<td>*JIS </td><td>Japanese Industrial Standard Christian Era </td><td>hh:mm:ss </td><td> : </td><td>04:25:15</td> </tr>
</tr>
</table>
</pre>
If no time format is specified, vvIn_time will try converting the browser input value from all
the formats listed above, in the order shown, until a successful conversion is made. If the value can not be
converted, then a time of midnight (all zeros) is returned and an error is sent to the Valence Error Log.
@return {time (*ISO format)} timeValue the time value sent from the browser
## RPG Example
d ordertime s t
/copy qcpylesrc,vvDspec
/free
// the browser has sent in a variable named "orderTime",
// retrieve the value and place it in the orderTime variable.
// since we are not quite sure of the date format being sent in, omit the
// optional date format parameter
//
orderTime = vvIn_time('orderTime');
// suppose we know the time format being sent in from the browser...
orderTime = vvIn_time('orderTime':'*USA');
/end-free
*/
/**
@method _timestamp
Retrieves post/get variables from the browser and returns a RPG timestamp variable.
@param {50a, const varying (required)} variableName A character expression representing the name of the variable sent in from the browser.
@param {4a, const varying (optional)} timestampFormat A character expression representing the expected
timestamp format of the variable passed in from the browser. Two formats are available: `*ISO` and `*ISO0` where the
*ISO0 format contains no separators. The timestamp must be in the format of yyyy-mm-dd-hh.mm.ss.nnnnnn with only the
separators as provided, or yyyymmddhhmmssnnnnnn for *ISO0 format.
If the timestampFormat is not provided and the value from the browser is not a valid timestamp, then the separators from
the browser variable are stripped out and the numeric value converted. If the value from the browser can not be converted
then a timestamp of 0001-01-01-00.00.00.000000 is returned and an error is sent to the Valence Error Log.
@return {timestamp} timestampValue The timestamp passed from the browser.
## RPG Example
d ordertimestamp s z
/copy qcpylesrc,vvDspec
/free
// the browser has sent in a variable named "orderTimestamp",
// retrieve the value and place it in the orderTimestamp variable.
// since we are not quite sure of the date format being sent in, omit the
// optional date format parameter
//
orderTimestamp = vvIn_timestamp('orderTimestamp');
// suppose we know the time format being sent in from the browser...
orderTimestamp = vvIn_timestamp('orderTime':'*ISO0');
/end-free
*/
/**
@method _utf16
Retrieves post/get variables from the browser.
NOTE: This procedure is meant to be used in tandem with variables encoded using Valence.util.encodeUTF16
from the JavaScript front-end program.
@param {50a, const varying (required)} variableName A character expression representing the name of the variable sent in from the browser
@param {1p0, const (optional)} formatOption Optionally adjusts the data being returned from the browser. The VVDSPEC copy source member contains two formatting constants:
- `TOUPPER` Format the returned graphic string to all uppercase
- `TOLOWER` Format the returned graphic string to all lowercase
@return {16370c varying} graphicValue The graphic field equivalent passed from the browser
## RPG Example
d orderNum s 6 0
d description s 500c
/copy qcpylesrc,vvDspec
/free
// the browser has sent in a variable named "description"
// the value of which was encoded using Valence.util.encodeUTF16...
//
description = vvIn_UTF16('description');
/end-free
*/