pixiSetBoxRangeForPicklist · Pixi API documentation

Assigns the box range BoxNrFrom–BoxNrTo to the picklist Picklist.

The call validates the input in this order and stops at the first failure, returning a row with Status = Error and a Message:

The picklist must exist in PLHeader.
BoxNrFrom must exist as a box in boxes.
BoxNrTo must exist as a box in boxes.
BoxNrTo must not be smaller than BoxNrFrom.
If the setting Picklist_Creation_Allow_BoxRange_OverLap is 0, no box number in the requested range may lie within the box range of any other picklist.
The number of distinct orders on the picklist (via its picklist items and order lines) must not exceed the number of free boxes in the range. A box counts as free if its BOrderNr is NULL or 0.

If all checks pass, the call:

deletes all existing box assignments of the picklist from pixi.PicklistBox,
writes the new range into PLHeader.PLHfromBox / PLHeader.PLHtoBox,
returns one row with the picklist key, the new range and a status text. The text says set if the picklist had no complete range before, otherwise changed.

Notes

The delete and update run in a transaction. If the call is already inside an open transaction, a savepoint is used instead and the outer transaction is not committed.
On an unexpected SQL error the transaction (or savepoint) is rolled back, a row with Status = Error and the SQL error text is returned, and the error is logged via log.InsertError (definition not attached).
Validation queries use NOLOCK, so concurrent changes may not be seen.
The overlap check only runs if the setting value equals 0. If the setting is missing (NULL) or has another value, overlapping ranges are allowed. The check relies on the Numbers helper table, so box numbers beyond its range are not checked.
Boxes that already hold an order (BOrderNr set) count as unavailable, even if that order belongs to the same picklist.
A former check that blocked changes once items of the picklist had been put into boxes was removed for backward compatibility. The range can therefore be changed even after items have been put into boxes; existing pixi.PicklistBox assignments are deleted in any case.
The success status text contains the spelling succesfully exactly as produced by the code.

Tables used

PLHeader · Write PicklistBox · Write boxes · Read Numbers · Read PLitem · Read Orderlines · Read Settings · Read

Parameter	Type	Default	Description
`Picklist` Required	int	–	Key of the picklist (`PLHeader.PLHkey`) whose box range is set. Example: `4711`
`BoxNrFrom` Required	int	–	First box number of the range. Must exist in `boxes`. Example: `1`
`BoxNrTo` Required	int	–	Last box number of the range. Must exist in `boxes` and must not be smaller than `BoxNrFrom`. Example: `20`

Result set 1 · If a validation fails or an unexpected SQL error occurs

Error row describing why the box range was not set.

Column	Type	Description
`Status`	varchar(5) string	Always `Error`.
`Message` Nullable	nvarchar(4000) string	Error text from the validation or the SQL error message.

Result set 2 · On success

The picklist with its new box range and a status text.

Column	Type	Description
`Picklist`	int	Picklist key (`PLHeader.PLHkey`).
`BoxNrFrom` Nullable	int	New first box number (`PLHeader.PLHfromBox`).
`BoxNrTo` Nullable	int	New last box number (`PLHeader.PLHtoBox`).
`Status`	varchar(70) string	`BoxRange for picklist(<id>) was succesfully set` if the picklist had no complete range before, otherwise `... was succesfully changed`.

Response example

<SqlRowSet1>
  <row>
    <Picklist>4711</Picklist>
    <BoxNrFrom>1</BoxNrFrom>
    <BoxNrTo>20</BoxNrTo>
    <Status>BoxRange for picklist(4711) was succesfully changed</Status>
  </row>
</SqlRowSet1>

Status	Message	Cause
Error	Picklist ({Picklist}) does not exist.	No picklist with the given key exists in `PLHeader`, or `Picklist` is NULL. Pass an existing picklist key.
Error	Box number ({BoxNrFrom}) provided by BoxNrFrom parameter does not exist.	The box `BoxNrFrom` does not exist in `boxes` or is NULL.
Error	Box number ({BoxNrTo}) provided by BoxNrTo parameter does not exist.	The box `BoxNrTo` does not exist in `boxes` or is NULL.
Error	Parameter BoxNrTo ({BoxNrTo}) is smaller than parameter BoxNrFrom ({BoxNrFrom}).	The range is reversed. Pass `BoxNrTo` >= `BoxNrFrom`.
Error	BoxRange for picklist could not be changed since some boxes in the range are already reserved for another picklist.	Overlapping ranges are not allowed (setting `Picklist_Creation_Allow_BoxRange_OverLap` = 0) and at least one box in the range belongs to the range of another picklist. Choose a free range.
Error	There are more orders on the picklist than available boxes in the selected box range.	The number of distinct orders on the picklist exceeds the number of boxes in the range without an assigned order. Enlarge the range or free boxes.
Error	{ERROR_MESSAGE()}	An unexpected SQL error occurred while deleting box assignments or updating the picklist. The changes are rolled back and the error is logged.

POST https://apigateway.descartes.com/tms/pixi/
Content-Type: text/xml; charset=utf-8
Authorization: Basic BASE64(USERNAME:PASSWORD)

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://apigateway.descartes.com/tms/pixi/">
  <SOAP-ENV:Body>
    <ns1:pixiSetBoxRangeForPicklist>
      <Picklist>4711</Picklist>
      <BoxNrFrom>1</BoxNrFrom>
      <BoxNrTo>20</BoxNrTo>
    </ns1:pixiSetBoxRangeForPicklist>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

curl -X POST 'https://apigateway.descartes.com/tms/pixi/' \
  --user 'USERNAME:PASSWORD' \
  --header 'Content-Type: text/xml; charset=utf-8' \
  --data-binary @- <<'XML'
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://apigateway.descartes.com/tms/pixi/">
  <SOAP-ENV:Body>
    <ns1:pixiSetBoxRangeForPicklist>
      <Picklist>4711</Picklist>
      <BoxNrFrom>1</BoxNrFrom>
      <BoxNrTo>20</BoxNrTo>
    </ns1:pixiSetBoxRangeForPicklist>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML

<?php

$soapClient = new SoapClient(null, [
    'login' => 'USERNAME',
    'password' => 'PASSWORD',
    'location' => 'https://apigateway.descartes.com/tms/pixi/',
    'uri' => 'https://apigateway.descartes.com/tms/pixi/',
]);

$arguments = [
    'Picklist' => '4711',
    'BoxNrFrom' => '1',
    'BoxNrTo' => '20',
];

$soapArguments = [];
foreach ($arguments as $name => $value) {
    $soapArguments[] = new SoapVar($value, XSD_STRING, '', '', $name);
}

$response = $soapClient->__soapCall('pixiSetBoxRangeForPicklist', $soapArguments);