# UPS_adrVld()

This subprocedure calls the UPS Address Validation API for city/state/zip address validation. It reads in request data from UPSAVRQ and writes response data to UPSAVRS.

## Subprocedure Prototype

| Field | Description |
|---|---|
| `     D UPS_adrVld      PR              N` | Returns *OFF if an error occurs during processing, *ON otherwise. |
| `     D  pUniqueID                    15P 0` | The ID of the record in UPSAVRQ that will be used to build the request, and under which the response data will be saved in UPSAVRS. |
| `     D  pErrorDS                           LikeDS(UPS_Error)` | The data structure in which error information will be returned. |


## Example Code

### T_AV - Address Validation
```rpgle
      *------------------------------------------------------------------------
      * @Author: Kato Integrations
      * @Description:
      *   This is a test program to illustrate how to call the UPS_adrVld()
      *   subprocedure to perform a non-street-level address validation.
      *
      *   To achieve this, generate a unique ID with UPS_getUID(), and
      *   then populate and write a record to UPSAVRQ. Then, call
      *   UPS_adrVld() passing in your unique ID as well as the other
      *   parameters shown.
      *
      *   UPS_adrVld() 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 UPSAVRS physical
      *   file, and retrieve the result fields.
      *------------------------------------------------------------------------
     H DFTACTGRP(*NO) ACTGRP(*NEW) BNDDIR('UPSBND') OPTION(*NODEBUGIO)

     FUPSAVRQ   UF A E           K DISK    Qualified
     FUPSAVRS   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 AVRQ            DS                  Likerec(UPSAVRQ.RUPSAVRQ:*Output)
     D AVRS            DS                  Likerec(UPSAVRS.RUPSAVRS:*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 AVRQ;
       AVRQ.UID = UniqueID;
       // Populate this field with application name set up using WRKUPSAUTH
       AVRQ.UserID = 'KATO_TEST';

       AVRQ.State = 'MN';
       AVRQ.PostCD = '56001';
       write UPSAVRQ.RUPSAVRQ AVRQ;

       // If UPS_adrVld() returns *Off, an error occurred and UPS_ErrorDS
       //  should be reviewed to determine the cause.
       if not UPS_adrVld( 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 UPSAVRS.RUPSAVRS;
         if not %Found(UPSAVRS);
           WriteToJobLog( 'ERROR: No results found in UPSAVRS' + NewLine );
           exsr cleanup;
           return;
         endif;

         // Read the results from UPSAVRS. 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 UPSAVRS.RUPSAVRS AVRS;
         dow not %Eof(UPSAVRS);
           WriteToJobLog( 'Result Record: ' + NewLine );
           WriteToJobLog( 'PID: ' + %Char(AVRS.PID) + NewLine );
           WriteToJobLog( 'UID: ' + %Char(AVRS.UID) + NewLine );
           WriteToJobLog( 'RANK: ' + %Char(AVRS.RANK) + NewLine );
           WriteToJobLog( 'QUALITY: ' + %Char(AVRS.QUALITY) + NewLine );
           WriteToJobLog( 'CITY: ' + %Trim(AVRS.CITY) + NewLine );
           WriteToJobLog( 'STATE: ' + %Trim(AVRS.STATE) + NewLine );
           WriteToJobLog( 'POSTCDL: ' + %Trim(AVRS.POSTCDL) + NewLine );
           WriteToJobLog( 'POSTCDH: ' + %Trim(AVRS.POSTCDH) + NewLine );
           WriteToJobLog( '==========' + NewLine );
           reade UniqueID UPSAVRS.RUPSAVRS AVRS;
         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

### UPSAVRQ.pf

| Field | Description |
|---|---|
| `A          R RUPSAVRQ` | **Record** AV Request Record |
| `A           UID           15P 0` | **Key** Record Unique ID |
| `A           USERID        30A` | UPS User ID |
| `A           CITY          40A` | City |
| `A           STATE          5A` | State |
| `A           POSTCD        16A` | Postal Code |


## Output Table Files

### UPSAVRS.pf

| Field | Description |
|---|---|
| `A          R RUPSAVRS` | **Record** Address Validation Response Record |
| `A            PID           15P 0` | **Key** Parent Unique ID |
| `A            UID           15P 0` | **Key** Child Unique ID |
| `A            RANK          10P 0` | Result Rank |
| `A            QUALITY        3P 2` | Result Quality |
| `A            CITY          40A` | City |
| `A            STATE          5A` | State |
| `A            POSTCDL       16A` | Postal Code Low |
| `A            POSTCDH       16A` | Postal Code High |