Orderlines Schreiben

pixiBreakOrderline

Teilt eine Auftragsposition in zwei Positionen auf, indem eine angegebene Menge in eine neue Auftragsposition übertragen wird, optional mit neuem Status.

Teilt eine bestehende Auftragsposition, die über OrderlineKey angegeben wird, in zwei Auftragspositionen auf. Der Aufruf ist ein schlanker Wrapper um die interne Prozedur GOSBreakOrderline. Alle Parameter werden unverändert durchgereicht.

Ablauf:

GOSBreakOrderline wird mit OrderlineKey, NewQty, NewStatus, InvlineRef, UserName und BinRef ausgeführt. Die internen Parameter TermID, LargeOrderToBreak und PLHKey behalten ihre Standardwerte.
GOSBreakOrderline startet eine Transaktion oder setzt einen Savepoint, falls bereits eine Transaktion offen ist. Anschließend wird eine exklusive Anwendungssperre mit dem Namen Orderline_<OrderlineKey> und 5 Sekunden Timeout angefordert. Danach erfolgt die eigentliche Aufteilung über GOSBreakOrderline_Base.
Die innere Prozedur liefert eine Zeile mit Success und NewOrderlineKey. Der Wrapper speichert diese Zeile intern und gibt sie nicht an den Aufrufer weiter.
Ist der gespeicherte Wert Success ungleich 1, löst der Aufruf einen Fehler mit Schweregrad 11 aus.

Bei Erfolg liefert der Aufruf keine Ergebnismenge. Der Schlüssel der neu angelegten Auftragsposition wird nicht zurückgegeben. Er muss anschließend ermittelt werden, zum Beispiel durch erneutes Lesen der Auftragspositionen des Auftrags.

Hinweise

Die eigentliche Aufteilungslogik liegt in GOSBreakOrderline_Base, das nicht beigefügt ist. Folgende Punkte lassen sich aus dem vorliegenden Code nicht ableiten: die genaue Bedeutung von NewQty (Menge der neuen oder der verbleibenden Position), die gültigen Werte von NewStatus, die Wirkung von InvlineRef und BinRef sowie die geänderten Tabellen.
GOSBreakOrderline verwendet pro Auftragsposition eine exklusive Anwendungssperre (sp_getapplock, 5 Sekunden Timeout). Gleichzeitige Aufteilungen derselben Position werden dadurch serialisiert. Kann die Sperre nicht erlangt werden, wird intern der Fehler Could not obtain the lock ausgelöst.
Fehler innerhalb von GOSBreakOrderline werden abgefangen. Die Transaktion wird zurückgerollt und der Fehler über log.InsertError protokolliert. Ob der ursprüngliche Fehler danach beim Aufrufer ankommt, hängt von log.InsertError ab, das nicht beigefügt ist.
Das Ergebnis der inneren Prozedur wird per INSERT ... EXEC übernommen. Ein ROLLBACK innerhalb eines INSERT ... EXEC kann selbst einen SQL-Server-Fehler verursachen. Fehler können daher mit einer anderen Meldung als erwartet auftreten.
Stolperfalle: Liefert die innere Prozedur keine Zeile, ergibt die Prüfung auf Success NULL. In diesem Fall wird kein Fehler ausgelöst, obwohl möglicherweise nichts aufgeteilt wurde.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`OrderlineKey` Pflicht	integer int	–	Schlüssel der Auftragsposition, die aufgeteilt werden soll. Wird auch für den Namen der Anwendungssperre `Orderline_<OrderlineKey>` verwendet. Beispiel: `123456`
`NewQty` Pflicht	integer int	–	Menge für die Aufteilung. Wird an `GOSBreakOrderline_Base` übergeben; die genaue Bedeutung wird dort festgelegt. Beispiel: `2`
`NewStatus`	varchar(3) string	–	Optionaler Positionsstatus für die abgeteilte Position. Ein leerer String bedeutet, dass kein Status explizit vorgegeben wird. Die gültigen Werte werden in der inneren Prozedur geprüft. Beispiel: `AUF`
`InvlineRef`	int	0	Optionale Referenz auf eine Rechnungsposition, wird an die Aufteilungslogik durchgereicht. `0` bedeutet keine Referenz. Beispiel: `0`
`UserName`	varchar(50) string	NULL	Name des Benutzers, der die Aufteilung ausführt, wird an die Aufteilungslogik durchgereicht. Beispiel: `shopsync`
`BinRef`	int	NULL	Optionale Referenz auf einen Lagerplatz, wird an die Aufteilungslogik durchgereicht. Beispiel: `4711`

Antwort

Dieser Call liefert kein Result-Set.

Fehlermeldungen

Status	Meldung	Ursache
RAISERROR	GOSBreakOrderline not successful in procedure: pipiBreakOrderline	Die innere Prozedur `GOSBreakOrderline` hat für `Success` einen Wert ungleich 1 gemeldet, die Auftragsposition konnte also nicht aufgeteilt werden. Auftragspositionsschlüssel, Menge und Status prüfen.
RAISERROR	Could not obtain the lock	Wird in `GOSBreakOrderline` ausgelöst, wenn die exklusive Sperre auf die Auftragsposition nicht innerhalb von 5 Sekunden erlangt werden kann, etwa weil ein anderer Prozess dieselbe Position aufteilt. Der Fehler wird abgefangen und protokolliert; ob er beim Aufrufer ankommt, hängt von `log.InsertError` ab. Später erneut versuchen.

Beispiele

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:pixiBreakOrderline>
      <OrderlineKey>123456</OrderlineKey>
      <NewQty>2</NewQty>
      <!-- <NewStatus>AUF</NewStatus> -->
      <!-- <InvlineRef>0</InvlineRef> -->
      <!-- <UserName>shopsync</UserName> -->
      <!-- <BinRef>4711</BinRef> -->
    </ns1:pixiBreakOrderline>
  </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:pixiBreakOrderline>
      <OrderlineKey>123456</OrderlineKey>
      <NewQty>2</NewQty>
      <!-- <NewStatus>AUF</NewStatus> -->
      <!-- <InvlineRef>0</InvlineRef> -->
      <!-- <UserName>shopsync</UserName> -->
      <!-- <BinRef>4711</BinRef> -->
    </ns1:pixiBreakOrderline>
  </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 = [
    'OrderlineKey' => '123456',
    'NewQty' => '2',
    // 'NewStatus' => 'AUF',
    // 'InvlineRef' => '0',
    // 'UserName' => 'shopsync',
    // 'BinRef' => '4711',
];

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

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

SQL-Objekt:: dbo.pipiBreakOrderline