# UPS_sAdrVld() This subprocedure calls the UPS Street-Level Address Validation API. It reads request data from UPSXVRQ, and writes response data to UPSXVRS. ## Subprocedure Prototype | Field | Description | |---|---| | ` D UPS_sAdrVld PR N` | Returns *OFF if an error occurs during processing, *ON otherwise. | | ` D pUniqueID 15P 0` | The ID of the record in UPSXVRQ that will be used to build the request, and under which the response data will be saved in UPSXVRS. | | ` D pErrorDS LikeDS(UPS_Error)` | The data structure in which error information will be returned. | ## Example Code ### T_XV - Street-Level Address Validation ```rpgle *------------------------------------------------------------------------ * @Author: Kato Integrations * @Description: * This is a test program to illustrate how to call the UPS_sAdrVld() * subprocedure to perform a street-level address validation. * * To achieve this, generate a unique ID with UPS_getUID(), and * then populate and write a record to UPSXVRQ. Then, call * UPS_sAdrVld() passing in your unique ID as well as the other * parameters shown. * * UPS_sAdrVld() will return *On if no error was encountered, or *Off * if an error occurred. If an error occurred, you should look at * the fields in ErrorDS to retrieve information about the error. * * Otherwise, you can perform a CHAIN against the UPSXVRS physical * file, and retrieve the result fields. *------------------------------------------------------------------------ H DFTACTGRP(*NO) ACTGRP(*NEW) BNDDIR('UPSBND') OPTION(*NODEBUGIO) FUPSXVRQ UF A E K DISK Qualified FUPSXVRS IF A E K DISK Qualified /COPY QRPGLECPY,UPS // This is included for demo output purposes. D WriteToJobLog PR 10I 0 Extproc('Qp0zLprintf') D pString * Value Options(*String) D NewLine C x'15' D XVRQ DS Likerec(UPSXVRQ.RUPSXVRQ:*Output) D XVRS DS Likerec(UPSXVRS.RUPSXVRS:*Input) D ErrorDS DS LikeDS(UPS_ErrorDS_t) Inz(*LikeDS) D UniqueID S Like(UPS_UniqueID_t) /FREE reset ErrorDS; // Retrieve Unique ID used to identify this request UniqueID = UPS_getUID(); clear XVRQ; XVRQ.UID = UniqueID; // Populate this field with application name set up using WRKUPSAUTH XVRQ.UserID = 'KATO_TEST'; XVRQ.Addr1 = '4706 Chiquita Blvd S'; XVRQ.City = 'Cape Coral'; XVRQ.State = 'FL'; XVRQ.PostCD = '33914'; XVRQ.Cntry = 'US'; write UPSXVRQ.RUPSXVRQ XVRQ; // If UPS_sAdrVld() returns *Off, an error occurred and UPS_ErrorDS // should be reviewed to determine the cause. if not UPS_sAdrVld( UniqueID : ErrorDS ); WriteToJobLog( 'API Error: ' + NewLine ); WriteToJobLog( 'Error Code: ' + %Trim(ErrorDS.Code) + NewLine ); WriteToJobLog( 'Error Severity: ' + %Char(ErrorDS.Severity) + NewLine ); WriteToJobLog( 'Error Source: ' + %Trim(ErrorDS.Pgm) + NewLine ); WriteToJobLog( 'Error Text: ' + %Trim(ErrorDS.Text) + NewLine ); exsr cleanup; return; else; setll UniqueID UPSXVRS.RUPSXVRS; if not %Found(UPSXVRS); WriteToJobLog( 'ERROR: No results found in UPSXVRS' + NewLine ); exsr cleanup; return; endif; // Read the results from UPSXVRS. There are typically multiple // records. A selection of the available fields is output by // this example program but more are availble - review the file // to see what else is available. reade UniqueID UPSXVRS.RUPSXVRS XVRS; dow not %Eof(UPSXVRS); WriteToJobLog( 'Result Record: ' + NewLine ); WriteToJobLog( 'PID: ' + %Char(XVRS.PID) + NewLine ); WriteToJobLog( 'UID: ' + %Char(XVRS.UID) + NewLine ); WriteToJobLog( 'NOCANDS: ' + %Trim(XVRS.NOCANDS) + NewLine ); WriteToJobLog( 'VALIDADDR: ' + %Trim(XVRS.VALIDADDR) + NewLine ); WriteToJobLog( 'AMBGADDR: ' + %Trim(XVRS.AMBGADDR) + NewLine ); WriteToJobLog( 'CLSCD: ' + %Trim(XVRS.CLSCD) + NewLine ); WriteToJobLog( 'CLSDSC: ' + %Trim(XVRS.CLSDSC) + NewLine ); WriteToJobLog( 'ADDR1: ' + %Trim(XVRS.ADDR1) + NewLine ); WriteToJobLog( 'ADDR2: ' + %Trim(XVRS.ADDR2) + NewLine ); WriteToJobLog( 'ADDR3: ' + %Trim(XVRS.ADDR3) + NewLine ); WriteToJobLog( 'CITY: ' + %Trim(XVRS.CITY) + NewLine ); WriteToJobLog( 'STATE: ' + %Trim(XVRS.STATE) + NewLine ); WriteToJobLog( 'POSTCD: ' + %Trim(XVRS.POSTCD) + NewLine ); WriteToJobLog( 'CNTRY: ' + %Trim(XVRS.CNTRY) + NewLine ); WriteToJobLog( '==========' + NewLine ); reade UniqueID UPSXVRS.RUPSXVRS XVRS; enddo; endif; exsr cleanup; return; begsr cleanup; // Always call UPS_cleanup() any time your program will terminate UPS_cleanup(); *INLR = *ON; endsr; /END-FREE ``` ## Data Structures ### UPS_Error | Field | Description | |---|---| | ` D UPS_Error DS Qualified Inz` | | | ` D Code 10A` | Error code raised by subprocedure | | ` D Severity 10I 0` | Severity of error - will be either UPS_SEVERE or UPS_INFO | | ` D Pgm 30A Varying` | Name of subprocedure that raised the error | | ` D Text 32000A Varying` | Error message text | ## Input Table Files ### UPSXVRQ.pf | Field | Description | |---|---| | `A R RUPSXVRQ` | **Record** Street-Level Address Validation Request Record | | `A UID 15P 0` | **Key** Record Unique ID | | `A USERID 30A` | UPS User ID | | `A ADDR1 35A` | Address Line 1 | | `A ADDR2 35A` | Address Line 2 | | `A ADDR3 35A` | Address Line 3 | | `A CITY 40A` | City | | `A STATE 5A` | State | | `A POSTCD 16A` | Postal Code/Zip | | `A CNTRY 2A` | Country | ## Output Table Files ### UPSXVRS.pf | Field | Description | |---|---| | `A R RUPSXVRS` | **Record** Street-Level Address Validation Response Record | | `A PID 15P 0` | **Key** Parent Unique ID | | `A UID 15P 0` | **Key** Child Unique ID | | `A NOCANDS 1A` | No Candidates Indicator **Valid Values:** `T`, `F` | | `A CLSCD 1A` | Address Class Code | | `A CLSDSC 15A` | Address Class Description | | `A ADDR1 35A` | Address Line 1 | | `A ADDR2 35A` | Address Line 2 | | `A ADDR3 35A` | Address Line 3 | | `A CITY 40A` | City | | `A STATE 5A` | State | | `A POSTCD 16A` | Postal Code/Zip | | `A CNTRY 2A` | Country | | `A VALIDADDR 1A` | Valid Address Indicator **Valid Values:** `T`, `F` | | ` A AMBGADDR 1A` | Ambiguous Address Indicator **Valid Values:** `T`, `F` |