InvokeRetrieve

Runtime verified Test scripts included

Syntax

InvokeRetrieve(retrieveRequest[, @statusMessage, @requestId])  →  rowset

1–3 arguments

The read-only executor. Runs the SOAP Retrieve on a RetrieveRequest built with CreateObject and returns a rowset — read it with RowCount, Row and Field. Unlike the write executors, the return value is the data, not a status string; the OverallStatus goes to the @statusMessage out-variable.

Parameters

Name	Type	Required	Description
`retrieveRequest`	object	Yes	A `RetrieveRequest` built with `CreateObject`
`@statusMessage`	string	No	Out-variable that receives the OverallStatus
`@requestId`	string	No	Out-variable that receives the RequestID

Example

%%[
  VAR @rr, @st, @req, @rows
  SET @rr = CreateObject("RetrieveRequest")
  SetObjectProperty(@rr, "ObjectType", "DataExtension")
  AddObjectArrayItem(@rr, "Properties", "Name")
  AddObjectArrayItem(@rr, "Properties", "CustomerKey")
  VAR @sfp
  SET @sfp = CreateObject("SimpleFilterPart")
  SetObjectProperty(@sfp, "Property", "CustomerKey")
  SetObjectProperty(@sfp, "SimpleOperator", "equals")
  AddObjectArrayItem(@sfp, "Value", "MY_DE")
  SetObjectProperty(@rr, "Filter", @sfp)
  SET @rows = InvokeRetrieve(@rr, @st, @req)
  OutputLine(Concat("st=[", @st, "] rc=[", RowCount(@rows), "]"))
]%%

Renders st=[OK] rc=[1] when a data extension with that key exists.

Return value

rowset — the retrieved rows; iterate with RowCount, Row and Field. The @statusMessage out-variable receives the OverallStatus (OK on a successful call) and @requestId receives the RequestID.

Behaviour

A match returns a populated rowset with status OK. Retrieving a data extension definition by CustomerKey filter returned st=OK, rc=1, with the Name and CustomerKey fields readable from row 1.

A no-match returns an empty rowset, not an error. Filtering on a nonexistent CustomerKey returned st=OK with rc=0 — an empty result, not a failure. Test for “not found” by checking RowCount, never by expecting an error status.

Show test script

%%[
  VAR @b
  SET @b = RequestParameter("b")

  IF @b == "zzz" THEN
    OutputLine(Concat("CTRL=[alive]"))
  ENDIF

  /* a match returns a populated rowset with status OK */
  IF @b == "hit" THEN
    VAR @rr, @st, @req, @rows, @sfp
    SET @rr = CreateObject("RetrieveRequest")
    SetObjectProperty(@rr, "ObjectType", "DataExtension")
    AddObjectArrayItem(@rr, "Properties", "Name")
    AddObjectArrayItem(@rr, "Properties", "CustomerKey")
    SET @sfp = CreateObject("SimpleFilterPart")
    SetObjectProperty(@sfp, "Property", "CustomerKey")
    SetObjectProperty(@sfp, "SimpleOperator", "equals")
    AddObjectArrayItem(@sfp, "Value", "AMP_VERIFY_SCRATCH")
    SetObjectProperty(@rr, "Filter", @sfp)
    SET @rows = InvokeRetrieve(@rr, @st, @req)
    OutputLine(Concat("hit st=[", @st, "] rc=[", RowCount(@rows), "]"))
    IF RowCount(@rows) > 0 THEN
      VAR @r1
      SET @r1 = Row(@rows, 1)
      OutputLine(Concat("row1 Name=[", Field(@r1, "Name"), "]"))
    ENDIF
  ENDIF

  /* a no-match returns an empty rowset with status OK, not an error */
  IF @b == "miss" THEN
    VAR @rr, @st, @req, @rows, @sfp
    SET @rr = CreateObject("RetrieveRequest")
    SetObjectProperty(@rr, "ObjectType", "DataExtension")
    AddObjectArrayItem(@rr, "Properties", "Name")
    SET @sfp = CreateObject("SimpleFilterPart")
    SetObjectProperty(@sfp, "Property", "CustomerKey")
    SetObjectProperty(@sfp, "SimpleOperator", "equals")
    AddObjectArrayItem(@sfp, "Value", "_no_such_de_zzz_9988")
    SetObjectProperty(@rr, "Filter", @sfp)
    SET @rows = InvokeRetrieve(@rr, @st, @req)
    OutputLine(Concat("miss st=[", @st, "] rc=[", RowCount(@rows), "]"))
  ENDIF
]%%

Availability

Platform	Available
Marketing Cloud Engagement	Yes
Marketing Cloud Next	No