# UPS_shipVoid()

This subprocedure calls the UPS Void Shipment API. It reads request data from UPSSVRQ and package data from UPSSVRQPK. It writes response data to UPSSVRS and package data to UPSSVRSPK.

## Subprocedure Prototype

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


## Example Code

### T_SV - Void Shipment
```rpgle
      *------------------------------------------------------------------------
      * @Author: Kato Integrations
      * @Description:
      *   This is a test program to illustrate how to call the
      *   UPS_shipVoid() subprocedure to void a shipment.
      *
      *   To achieve this, generate a unique ID with UPS_getUID(), and
      *   then populate and write a record to UPSSVRQ, and one or more child
      *   records to UPSSVRQPK if you need to use "expanded void" capability.
      *   Expanded voiding allows package-level voiding. Then, call
      *   UPS_shipVoid() passing in your unique ID as well as the other
      *   parameters shown.
      *
      *   UPS_shipVoid() 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 read the result data from UPSSVRS, and UPSSVRSPK
      *   if an expanded void was performed.
      *
      *   This example program is only going to demonstrate a basic void.
      *------------------------------------------------------------------------
     H DFTACTGRP(*NO) ACTGRP(*NEW) BNDDIR('UPSBND') OPTION(*NODEBUGIO)

     FUPSSVRQ   UF A E           K DISK    Qualified
     FUPSSVRS   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 SVRQ            DS                  Likerec(UPSSVRQ.RUPSSVRQ:*Output)
     D SVRS            DS                  Likerec(UPSSVRS.RUPSSVRS:*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 SVRQ;
       SVRQ.UID = UniqueID;
       // Populate this field with application name set up using WRKUPSAUTH
       SVRQ.UserID = 'KATO_TEST';

       // This is a sample shipping number provided by UPS to test shipment
       //  void operations.
       SVRQ.ShipNbr = '1ZISDE016691676846';

       // This is only used in an "expanded void" to allow package-level
       //  voiding. This is covered in example program T_SVEXP
       // SVRQ.ExpVoid = '';

       write UPSSVRQ.RUPSSVRQ SVRQ;

       // If UPS_shipVoid() returns *Off, an error occurred and
       //  UPS_ErrorDS should be reviewed to determine the cause.
       if not UPS_shipVoid( 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;

         // Read the results from UPSSVRS. There is only going to be one record
         chain UniqueID UPSSVRS.RUPSSVRS SVRS;
         if not %Found(UPSSVRS);
           WriteToJobLog( 'ERROR: No results found in UPSSVRS' + NewLine );
           exsr cleanup;
           return;
         endif;

         WriteToJobLog( 'Result Record: ' + NewLine );
         WriteToJobLog( 'UID: ' + %Char(SVRS.UID) + NewLine );
         WriteToJobLog( 'STSCD: ' + %Trim(SVRS.STSCD) + NewLine );
         WriteToJobLog( 'STSDSC: ' + %Trim(SVRS.STSDSC) + NewLine );
       endif;

       exsr cleanup;
       return;

       begsr cleanup;
         // Always call UPS_cleanup() any time your program will terminate
         UPS_cleanup();
         *INLR = *ON;
       endsr;

      /END-FREE
```

### T_SVEXP - Expanded/Partial Void Shipment
```rpgle
      *------------------------------------------------------------------------
      * @Author: Kato Integrations
      * @Description:
      *   This is a test program to illustrate how to call the
      *   UPS_shipVoid() subprocedure to void a shipment.
      *
      *   To achieve this, generate a unique ID with UPS_getUID(), and
      *   then populate and write a record to UPSSVRQ, and one or more child
      *   records to UPSSVRQPK if you need to use "expanded void" capability.
      *   Expanded voiding allows package-level voiding. Then, call
      *   UPS_shipVoid() passing in your unique ID as well as the other
      *   parameters shown.
      *
      *   UPS_shipVoid() 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 read the result data from UPSSVRS, and UPSSVRSPK
      *   if an expanded void was performed.
      *
      *   This example program performs an expanded void to void an individual
      *   package from a shipment.
      *------------------------------------------------------------------------
     H DFTACTGRP(*NO) ACTGRP(*NEW) BNDDIR('UPSBND') OPTION(*NODEBUGIO)

     FUPSSVRQ   UF A E           K DISK    Qualified
     FUPSSVRQPK UF A E           K DISK    Qualified
     FUPSSVRS   IF A E           K DISK    Qualified
     FUPSSVRSPK 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 SVRQ            DS                  Likerec(UPSSVRQ.RUPSSVRQ:*Output)
     D SVRQPK          DS                  Likerec(UPSSVRQPK.RUPSSVRQPK:*Output)
     D SVRS            DS                  Likerec(UPSSVRS.RUPSSVRS:*Input)
     D SVRSPK          DS                  Likerec(UPSSVRSPK.RUPSSVRSPK:*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 SVRQ;
       SVRQ.UID = UniqueID;
       // Populate this field with application name set up using WRKUPSAUTH
       SVRQ.UserID = 'KATO_TEST';

       // This is a sample shipping number provided by UPS to test shipment
       //  void operations.
       SVRQ.ShipNbr = '1Z2220060294314162';
       SVRQ.ExpVoid = 'T';
       write UPSSVRQ.RUPSSVRQ SVRQ;

       // When doing an expanded void, write one record to UPSSVRQPK for each
       //  package you wish to void from a shipment.
       clear SVRQPK;
       SVRQPK.PID = UniqueID;
       SVRQPK.UID = 1;

       // Package-level tracking number
       SVRQPK.TrackNbr = '1Z2220060291994175';
       write UPSSVRQPK.RUPSSVRQPK SVRQPK;

       // If UPS_shipVoid() returns *Off, an error occurred and
       //  UPS_ErrorDS should be reviewed to determine the cause.
       if not UPS_shipVoid( 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;

         // Read the results from UPSSVRS. There is only going to be one record
         chain UniqueID UPSSVRS.RUPSSVRS SVRS;
         if not %Found(UPSSVRS);
           WriteToJobLog( 'ERROR: No results found in UPSSVRS' + NewLine );
           exsr cleanup;
           return;
         endif;

         WriteToJobLog( 'Result Record: ' + NewLine );
         WriteToJobLog( 'UID: ' + %Char(SVRS.UID) + NewLine );
         WriteToJobLog( 'EXPVOID: ' + %Trim(SVRS.EXPVOID) + NewLine );
         WriteToJobLog( 'STSCD: ' + %Trim(SVRS.STSCD) + NewLine );
         WriteToJobLog( 'STSDSC: ' + %Trim(SVRS.STSDSC) + NewLine );

         // Read the results of each package-level void from UPSSVRSPK.
         chain UniqueID UPSSVRSPK.RUPSSVRSPK SVRSPK;
         if not %Found(UPSSVRSPK);
           WriteToJobLog( 'ERROR: No results found in UPSSVRSPK' + NewLine );
           exsr cleanup;
           return;
         endif;

         dow not %Eof(UPSSVRSPK);
           WriteToJobLog( 'Child Result Record: ' + NewLine );
           WriteToJobLog( 'PID: ' + %Char(SVRSPK.PID) + NewLine );
           WriteToJobLog( 'UID: ' + %Char(SVRSPK.UID) + NewLine );
           WriteToJobLog( 'TRACKNBR: ' + %Trim(SVRSPK.TRACKNBR) + NewLine );
           WriteToJobLog( 'STSCD: ' + %Trim(SVRSPK.STSCD) + NewLine );
           WriteToJobLog( 'STSDSC: ' + %Trim(SVRSPK.STSDSC) + NewLine );
           WriteToJobLog( '==========' + NewLine );
           reade UniqueID UPSSVRSPK.RUPSSVRSPK SVRSPK;
         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

### UPSSVRQ.pf

| Field | Description |
|---|---|
| `A          R RUPSSVRQ` | **Record** Shipment Void Request Record |
| `A            UID           15P 0` | **Key** Record Unique ID |
| `A            USERID        30A` | UPS User ID |
| `A            SHIPNBR       21A` | Shipment ID NUmber |
| `A            EXPVOID        1A` | Expanded Void Indicator **Valid Values:** `T`, `Y` |


### UPSSVRQPK.pf

| Field | Description |
|---|---|
| `A          R RUPSSVRQPK` | **Record** Shipment Void Request Package Information Record |
| `A            PID           15P 0` | **Key** Parent Unique ID |
| `A            UID           15P 0` | **Key** Child Unique ID |
| `A            TRACKNBR      21A` | Package Tracking Number |


## Output Table Files

### UPSSVRS.pf

| Field | Description |
|---|---|
| `A          R RUPSSVRS` | **Record** Shipment Void Response Record |
| `A            UID           15P 0` | **Key** Record Unique ID |
| `A            EXPVOID        1A` | Expanded Void Indicator **Valid Values:** `T`, `Y` |
| `A            STSCD          1A` | Void Status Code |
| `A            STSDSC        15A` | Void Status Description |


### UPSSVRSPK.pf

| Field | Description |
|---|---|
| `A          R RUPSSVRSPK` | **Record** Shipment Void Response Packge Information Record |
| `A            PID           15P 0` | **Key** Parent Unique ID |
| `A            UID           15P 0` | **Key** Child Unique ID |
| `A            TRACKNBR      21A` | Package Tracking Number |
| `A            STSCD          1A` | Void Status Code |
| `A            STSDSC        15A` | Void Status Description |