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

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


*------------------------------------------------------------------------ * @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

*------------------------------------------------------------------------ * @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

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

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

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

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

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