VFN_AddLineItem()

This subprocedure adds one or more line items (MERCHANDISE or OFFERs) to the display of a Verifone device by calling the Add Line Item service.

Subprocedure Prototype

IBM i 7.1+

`D VFN_AddLineItem... D PR N Extproc('VFN_AddLineItem')`	Returns OFF if an error occurs during processing, ON otherwise.
`D pRequestDS LikeDS(VFN_AddLineItemReqDS_t) Const`
`D pResponseDS LikeDS(VFN_AddLineItemRspDS_t)`
`D pErrorDS LikeDS(VFN_ErrorDS_t) D Options(*Nopass)`	Optional parameter that, if passed, will contain error data returned from the subprocedure.

Example Code


       // Example Program: T_ADLNITM
       // Description:
       //   This is a test program to illustrate how to use the
       //   VFN_AddLineItem() subprocedure to add a single MERCHANDISE line item
       //   to the display.
       //
       //   Please refer to T_ADDOFFR to see the same process for an OFFER line
       //   item.
       //
       //   This program assumes you have already called VFN_StartSession() to
       //   open a session with your device, and that you will call
       //   VFN_EndSession() afterwards.

       Ctl-Opt DftActGrp(*No) ActGrp(*Caller) BndDir('PTTIBND');

       /COPY QRPGLECPY,VFNCB

       // This is included for demo output purposes.
       Dcl-Pr WriteToJobLog Int(10) Extproc('Qp0zLprintf');
         pString Pointer Value Options(*String);
       End-Pr;
       Dcl-C NewLine x'15';

       // This will capture returned error information
       Dcl-Ds ErrorDS LikeDS(VFN_ErrorDS_t) Inz(*LikeDS);
       // This will be used to pass request information to the API call
       Dcl-Ds AddLineItemReqDS LikeDS(VFN_AddLineItemReqDS_t) Inz(*LikeDS);
       // This will store parsed response data from the API call
       Dcl-Ds AddLineItemRspDS LikeDS(VFN_AddLineItemRspDS_t) Inz(*LikeDS);

       reset ErrorDS;
       reset AddLineItemReqDS;
       reset AddLineItemRspDS;

       // This must be a device that has been successfully registered with
       //  VFN_Register() and which exists in VFNDVC.
       AddLineItemReqDS.DeviceID = 'test';

       // These fields can be assigned a log file path, and will save the
       //  request and response xml data.
       AddLineItemReqDS.RequestLog = 'T_ADLNITM_Request.xml';
       AddLineItemReqDS.ResponseLog = 'T_ADLNITM_Response.xml';

       // These fields are required for all line item transactions.
       AddLineItemReqDS.RunningTaxAmount = 2.42;
       AddLineItemReqDS.RunningTransAmount = 42.42;
       // This field is optional, but is included here for demonstration
       //  purposes.
       AddLineItemReqDS.RunningSubTotal = 40.00;

       AddLineItemReqDS.LineItems(1).LineItemID = '1';
       AddLineItemReqDS.LineItems(1).SKU = 'Example Merchandise';
       // Unless otherwise configured, this description must be 17 characters in
       //   length or less.
       AddLineItemReqDS.LineItems(1).Description = 'Item Description';
       AddLineItemReqDS.LineItems(1).UPC = '123456789012';
       AddLineItemReqDS.LineItems(1).Quantity = 0;
       AddLineItemReqDS.LineItems(1).UnitPrice = 20;
       AddLineItemReqDS.LineItems(1).ExtendedPrice = 40;

       // if VFN_AddLineItem() returns *Off, it means that an error occurred
       //  as part of the overall communication process, and the information
       //  will be in ErrorDS - ErrorDS.Message is the main field to look at
       //  for troubleshooting.
       if not VFN_AddLineItem( AddLineItemReqDS : AddLineItemRspDS
                              : ErrorDS );
         // handle error
         WriteToJobLog( 'Message ID: ' + ErrorDS.MessageId + NewLine );
         WriteToJobLog( 'Message: ' + ErrorDS.Message + NewLine );
         *INLR = *On;
         return;
       else;
         WriteToJobLog( 'Response Text: ' + AddLineItemRspDS.ResponseText
                      + NewLine);
         WriteToJobLog( 'Result: ' + AddLineItemRspDS.Result + NewLine );
         WriteToJobLog( 'Result Code: ' + AddLineItemRspDS.ResultCode
                      + NewLine );
         WriteToJobLog( 'Termination Status: '
                      + AddLineItemRspDS.TerminationStatus + NewLine );
       endif;

       *INLR = *On;
       return;


       // Example Program: T_ADDOFFR
       // Description:
       //   This is a test program to illustrate how to use the
       //   VFN_AddLineItem() subprocedure to add a single OFFER line item to
       //   the display.
       //
       //   Please refer to T_ADLNITM to see the same process for a MERCHANDISE
       //   line item.
       //
       //   This program assumes you have already called VFN_StartSession() to
       //   open a session with your device, and that you will call
       //   VFN_EndSession() afterwards.

       Ctl-Opt DftActGrp(*No) ActGrp(*Caller) BndDir('PTTIBND');

       /COPY QRPGLECPY,VFNCB

       // This is included for demo output purposes.
       Dcl-Pr WriteToJobLog Int(10) Extproc('Qp0zLprintf');
         pString Pointer Value Options(*String);
       End-Pr;
       Dcl-C NewLine x'15';

       // This will capture returned error information
       Dcl-Ds ErrorDS LikeDS(VFN_ErrorDS_t) Inz(*LikeDS);
       // This will be used to pass request information to the API call
       Dcl-Ds AddLineItemReqDS LikeDS(VFN_AddLineItemReqDS_t) Inz(*LikeDS);
       // This will store parsed response data from the API call
       Dcl-Ds AddLineItemRspDS LikeDS(VFN_AddLineItemRspDS_t) Inz(*LikeDS);

       reset ErrorDS;
       reset AddLineItemReqDS;
       reset AddLineItemRspDS;

       // This must be a device that has been successfully registered with
       //  VFN_Register() and which exists in VFNDVC.
       AddLineItemReqDS.DeviceID = 'test';

       // These fields can be assigned a log file path, and will save the
       //  request and response xml data.
       AddLineItemReqDS.RequestLog = 'T_ADDOFFR_Request.xml';
       AddLineItemReqDS.ResponseLog = 'T_ADDOFFR_Response.xml';

       // These fields are required for all line item transactions.
       AddLineItemReqDS.RunningTaxAmount = 2.42;
       AddLineItemReqDS.RunningTransAmount = 22.42;
       AddLineItemReqDS.LineItems(1).LineItemID = '2';
       AddLineItemReqDS.LineItems(1).SKU = 'Example Offer';
       // Unless otherwise configured, this description must be 17 characters in
       //  length or less.
       AddLineItemReqDS.LineItems(1).Description = 'BOGO Free';
       // This field can be used to change the display color of a line item.
       //  Here we are setting the line item to display in red.
       AddLineItemReqDS.LineItems(1).FontColValue = 'FF0000';
       // Refer to the VeriFone documentation for your device to find the valid
       //  values for the OFFER Type field.
       AddLineItemReqDS.LineItems(1).Type = 'MANUFACTURER_COUPON';
       AddLineItemReqDS.LineItems(1).OfferAmount = 20;
       // This field links the new OFFER line item to a MERCHANDISE line item
       //  that is already being displayed, or that has been added earlier in
       //  the same call to VFN_AddLineItem().
       AddLineItemReqDS.LineItems(1).OfferLineItem = '1';

       // if VFN_AddLineItem() returns *Off, it means that an error occurred
       //  as part of the overall communication process, and the information
       //  will be in ErrorDS - ErrorDS.Message is the main field to look at
       //  for troubleshooting.
       if not VFN_AddLineItem( AddLineItemReqDS : AddLineItemRspDS
                              : ErrorDS );
         // handle error
         WriteToJobLog( 'Message ID: ' + ErrorDS.MessageId + NewLine );
         WriteToJobLog( 'Message: ' + ErrorDS.Message + NewLine );
         *INLR = *On;
         return;
       else;
         WriteToJobLog( 'Response Text: ' + AddLineItemRspDS.ResponseText
                      + NewLine);
         WriteToJobLog( 'Result: ' + AddLineItemRspDS.Result + NewLine );
         WriteToJobLog( 'Result Code: ' + AddLineItemRspDS.ResultCode
                      + NewLine );
         WriteToJobLog( 'Termination Status: '
                      + AddLineItemRspDS.TerminationStatus + NewLine );
       endif;

       *INLR = *On;
       return;


       // Example Program: T_ADLNITMS
       // Description:
       //   This is a test program to illustrate how to use the
       //   VFN_AddLineItem() subprocedure to add a multiple line items to
       //   the display.
       //
       //   This example will show adding both a multi-line MERCHANDISE item and
       //   a single-line OFFER item.
       //
       //   This program assumes you have already called VFN_StartSession() to
       //   open a session with your device, and that you will call
       //   VFN_EndSession() afterwards.

       Ctl-Opt DftActGrp(*No) ActGrp(*Caller) BndDir('PTTIBND');

       /COPY QRPGLECPY,VFNCB

       // This is included for demo output purposes.
       Dcl-Pr WriteToJobLog Int(10) Extproc('Qp0zLprintf');
         pString Pointer Value Options(*String);
       End-Pr;
       Dcl-C NewLine x'15';

       // This will capture returned error information
       Dcl-Ds ErrorDS LikeDS(VFN_ErrorDS_t) Inz(*LikeDS);
       // This will be used to pass request information to the API call
       Dcl-Ds AddLineItemReqDS LikeDS(VFN_AddLineItemReqDS_t) Inz(*LikeDS);
       // This will store parsed response data from the API call
       Dcl-Ds AddLineItemRspDS LikeDS(VFN_AddLineItemRspDS_t) Inz(*LikeDS);

       reset ErrorDS;
       reset AddLineItemReqDS;
       reset AddLineItemRspDS;

       // This must be a device that has been successfully registered with
       //  VFN_Register() and which exists in VFNDVC.
       AddLineItemReqDS.DeviceID = 'test';

       // These fields can be assigned a log file path, and will save the
       //  request and response xml data.
       AddLineItemReqDS.RequestLog = 'T_ADLNITMS_Request.xml';
       AddLineItemReqDS.ResponseLog = 'T_ADLNITMS_Response.xml';

       // These fields are required for all line item transactions.
       AddLineItemReqDS.RunningTaxAmount = 5.42;
       AddLineItemReqDS.RunningTransAmount = 100.42;
       AddLineItemReqDS.LineItems(1).LineItemID = '3';
       AddLineItemReqDS.LineItems(1).SKU = 'Multi-Line MERCHANDISE';
       // Unless otherwise configured, this description must be 17 characters in
       //  length or less. This example specifically uses multiple LineItems to
       //  display a long description.
       AddLineItemReqDS.LineItems(1).Description = 'Description That';
       AddLineItemReqDS.LineItems(1).UPC = '210987654321';
       AddLineItemReqDS.LineItems(1).Quantity = 1;
       AddLineItemReqDS.LineItems(1).UnitPrice = 60;
       AddLineItemReqDS.LineItems(1).ExtendedPrice = 60;
       // To finish displaying the entire description, we need to add additional
       //  LineItems to the request. Each of these LineItems needs a unique ID.
       AddLineItemReqDS.LineItems(2).LineItemID = '4';
       AddLineItemReqDS.LineItems(2).Description = 'Is Too Long To';
       AddLineItemReqDS.LineItems(3).LineItemID = '5';
       AddLineItemReqDS.LineItems(3).Description = 'Display On A';
       AddLineItemReqDS.LineItems(4).LineItemID = '6';
       AddLineItemReqDS.LineItems(4).Description = 'Single Line';

       // OFFER LineItems can be added alongside MERCHANDISE LineItems.
       AddLineItemReqDS.LineItems(5).LineItemID = '7';
       AddLineItemReqDS.LineItems(5).Description = 'Sample OFFER';
       AddLineItemReqDS.LineItems(5).Type = 'LOYALTY_CARD';
       AddLineItemReqDS.LineItems(5).OfferAmount = 10;

       // if VFN_AddLineItem() returns *Off, it means that an error occurred
       //  as part of the overall communication process, and the information
       //  will be in ErrorDS - ErrorDS.Message is the main field to look at
       //  for troubleshooting.
       if not VFN_AddLineItem( AddLineItemReqDS : AddLineItemRspDS
                              : ErrorDS );
         // handle error
         WriteToJobLog( 'Message ID: ' + ErrorDS.MessageId + NewLine );
         WriteToJobLog( 'Message: ' + ErrorDS.Message + NewLine );
         *INLR = *On;
         return;
       else;
         WriteToJobLog( 'Response Text: ' + AddLineItemRspDS.ResponseText
                      + NewLine);
         WriteToJobLog( 'Result: ' + AddLineItemRspDS.Result + NewLine );
         WriteToJobLog( 'Result Code: ' + AddLineItemRspDS.ResultCode
                      + NewLine );
         WriteToJobLog( 'Termination Status: '
                      + AddLineItemRspDS.TerminationStatus + NewLine );
       endif;

       *INLR = *On;
       return;

Data Structures

`D VFN_AddLineItemReqDS_t... D DS Qualified Template Inz`
`D DeviceID Like(VFN_DeviceId_t)`	Required The ID of the payment device, registered in VFNDVC, on which line items are to be displayed.
`D RequestLog Like(VFN_Var1Kv_t)`	Specifies the file name or path of the request log file. Will have no effect if logging is not enabled. Example: `"req_log.txt","/tmp/logs/request.txt"`
`D ResponseLog Like(VFN_Var1Kv_t)`	Specifies the file name or path of the response log file. Will have no effect if logging is not enabled. Example: `"rsp_log.txt","/tmp/logs/response.txt"`
`D RunningSubTotal... D 8P 2`
`D RunningTaxAmount... D 8P 2`	Required Default Value: `0.00`
`D RunningTransAmount... D 8P 2`	Required Default Value: `0.00`
`D LineItems LikeDS(VFN_LineItemChildDS_t) Dim(10)`	Required This field will contain up to 10 child line item data structures, used to represent individual line items to be added.
`D ConnectTimeout... D 3P 0 Inz(-1)`	Override the default value set in VFN_Register() or REGVFNDVC. Default Value: `-1`
`D WriteTimeout... D 3P 0 Inz(-1)`	Override the default value set in VFN_Register() or REGVFNDVC. Default Value: `-1`
`D ReadTimeout... D 3P 0 Inz(-1)`	Override the default value set in VFN_Register() or REGVFNDVC. Default Value: `-1`

`D VFN_AddLineItemRspDS_t... D DS Qualified Template Inz`
`D ResponseText Like(VFN_Var1Kv_t)`	This field corresponds to the field RESPONSE_TEXT in your device's Verifone documentation.
`D Result Like(VFN_Var1Kv_t)`	This field corresponds to the field RESULT in your device's Verifone documentation.
`D ResultCode 10A Varying`	This field corresponds to the field RESULT_CODE in your device's Verifone documentation.
`D TerminationStatus... D Like(VFN_Var1Kv_t)`	This field corresponds to the field TERMINATION_STATUS in your device's Verifone documentation.
`D Counter 10P 0`	This field corresponds to the field COUNTER in your device's Verifone documentation.

`D VFN_LineItemChildDS_t... D DS Qualified Template Inz`
`D LineItemID 10A`	Required Each line item must be assigned a unique ID.
`D SKU 50A Varying`
`D Description 40A Varying`	This will be the text displayed on the payment device screen. Unless otherwise configured, the device will only accept lines up to 17 characters long. This field is required for OFFER child elements, and optional for MERCHANDISE child elements.
`D FontColValue 6A Inz('000000')`	This field can be used to specify the display color for the line item using hexadecimal notation. The default value corresponds to black, while the example would print the line item in red. Example: `'ff0000'` Default Value: `'000000'`
`D UPC Like(VFN_Var1Kv_t)`
`D Quantity 10P 0`
`D UnitPrice 8P 2`
`D ExtendedPrice 8P 2`	This will be the subtotal amount displayed for this line item.
`D Type Like(VFN_Var1Kv_t)`	Required For OFFER child elements only.
`D OfferAmount 8P 2`	Required For OFFER child elements only.
`D OfferLineItem 10A`