USE Builtin WITH_ARGS and TO_GET

[jyoung]

Every time I try to use Integrator and the use builtin command I get really confused.

One of the things I don't get is the difference between with_args and to_get. Given the documentation http://docs.lansa.com/14/en/LANSA015/Co ... .htm#USE_P it should be as simple as with_args are what you are passing to the function and to_get is what you expect out of the function. However this seems to not always be the case.

These examples are based on the PDFDocumentService.

Here is one example in the documentation http://docs.lansa.com/14/EN/lansa093/in ... 7_0835.htm that appears to passing a working list in the TO_GET.

Code: Select all

CHANGE     FIELD(#JSMCMD) TO('ADD CONTENT(TABLE) SERVICE_LIST(ID,FNAME,SNAME)')
USE        BUILTIN(JSM_COMMAND) WITH_ARGS(#JSMCMD) TO_GET(#JSMSTS #JSMMSG #TBLLST)
EXECUTE    SUBROUTINE(CHECK) WITH_PARMS(#JSMSTS #JSMMSG)

My own experience shows me that one way will work at one point and will not at another point.
For example, this works as expected, the list is passed to the template and the data shows up the pdf.

Code: Select all

#JSMXCMD := ('ADD CONTENT(OFFICE)')
use builtin(JSMX_COMMAND) with_args(#JSMXHDLE #JSMXCMD #CurrentOfficeList) to_get(#JSMXSTS #JSMXMSG)
if (#COM_OWNER.CheckStatus( #JSMXSTS #JSMXMSG ))
return
endif

This however does not work, this puts no data in the template.

Code: Select all

* Add Client List Content
#JSMXCMD := ('ADD CONTENT(CLIENT)')
use builtin(JSMX_COMMAND) with_args(#JSMXHDLE #JSMXCMD #DetailList) to_get(#JSMXSTS #JSMXMSG)
if (#COM_OWNER.CheckStatus( #JSMXSTS #JSMXMSG ))
return
endif

However, if I move the #DetailsList to to_get it works!

Code: Select all

#JSMXCMD := ('ADD CONTENT(CLIENT)')
use builtin(JSMX_COMMAND) with_args(#JSMXHDLE #JSMXCMD) to_get(#JSMXSTS #JSMXMSG #DetailList)
if (#COM_OWNER.CheckStatus( #JSMXSTS #JSMXMSG ))
return
endif

If it matters, here is the pdf template.

Code: Select all

<?xml version="1.0" encoding="utf-8"?>
<document page-size="A4" orientation = "portrait" background="white" border="false" author="Express Professionals" title="Sales Analysis" subject="Sales Analysis" keywords="Sales, Analysis" creator="JRYOUNG" hide-toolbar="" hide-menubar="" hide-windowui="" allow-printing="true" allow-copy="false" allow-modify-contents="false" allow-modify-annotations="false" allow-fillin="false" allow-screenreader="false" allow-assembly="false" allow-degraded-printing="false">
  <content name="office">
	  <text-align y1="800" align="center" value="{STD_STRNG}" />
    <text-align y1="780" align="center" value="Sales Analysis" />
    <text-align y1="760" align="center" value="{wk_StartDate}" />
  </content>
  <content name="client">
    <table x1="10" y1="740" width="400" style="normal" alternate="false">
      <column field="STD_STRNG" width-percentage="20" title="Name"/>
    </table>
    <page />>
  </content>
</document>

[Top Bloke]

http://docs.lansa.com/14/EN/lansa093/in ... MX_COMMAND

Arguments third parameter is a Field List.

Return Values third parameter is a Working List.

So check your list definitions.

[jyoung]

Ok, hate to be dense, but can you give me some more info?

This entry is VERY CONFUSING to me.

If an optional working list argument is specified then the fields defined in that list are available to the loaded service. If no working list argument is specified then no fields are available to the loaded service. This field list does not require an entry only the list definition is used to determine which fields are send to the JSM service.

If an optional working list return value is specified then that working list is available to the loaded service.

These two sentences in particular

If an optional working list argument is specified then the fields defined in that list are available to the loaded service

and

If an optional working list return value is specified then that working list is available to the loaded service.

So from what I understand, then a "field list" is an empty working list and a working list is a populated working list.
So a "field list" is a working list. Its simply a list of fields, that is empty.

So in order to get list data to the service, I have to define a "field list" and pass it in the WITH_ARGS parameter and then to actually pass the data I have to give the EXACT SAME LIST to TO_GET, that is supposed to be for return values.

I don't understand this at all.

Why would I put my "input" data to the "output" parameter?

[jyoung]

Following up,

If I want to pass fields (not a list) but actual fields then I have to create a empty list that has the fields I need want to pass in it. I then pass that list in the third param of WITH_ARGS.

For example, I want to pass STD_STRNG and STD_NUM to the BIF.

Code: Select all

* define a empty list that tells what fields we are passing to the BIF
def_list name(#MyFields) fields(#STD_STRNG #STD_NUM) type(*WORKING)

* passing the "fields" to the command
use builtin(JSMX_COMMAND) with_args(#JSMXHDLE #JSMXCMD #MyFields) to_get(#JSMXSTS #JSMXMSG)

If I want to pass an actual list, then I have to put the list in the TO_GET parameter.

Code: Select all

* define a empty list that tells what fields we are passing to the BIF
def_list name(#MyList) fields(#STD_STRNG #STD_NUM) type(*WORKING)

#STD_STRNG := "Hello"
#STD_NUM := 25
add_entry to_list(#MyList)

* passing the "list" to the command
use builtin(JSMX_COMMAND) with_args(#JSMXHDLE #JSMXCMD) to_get(#JSMXSTS #JSMXMSG #MyList)

However

From http://docs.lansa.com/14/EN/lansa093/in ... 5_0140.htm

Note: If a working list and the associated SERVICE_LIST keyword is used, then all fields are passed and a SERVICE_EXCHANGE(*FIELD) or SERVICE_EXCHANGE(*FIELDS) is not required on the same command.

If I use the "SERVICE_LIST" keyword, then the working list is ignored and ALL fields (not the list) get passed to the BIF.

Code: Select all

* define a empty list that tells what fields we are passing to the BIF
def_list name(#MyList) fields(#STD_STRNG #STD_NUM) type(*WORKING)

#STD_STRNG := "Hello"
#STD_NUM := 25
add_entry to_list(#MyList)

* ignores the list and ALL fields get passed
#JSMXCMD := 'ADD CONTENT(CLIENT) SERVICE_LIST(STD_STRNG STD_NUM)'
use builtin(JSMX_COMMAND) with_args(#JSMXHDLE #JSMXCMD) to_get(#JSMXSTS #JSMXMSG #MyList)

Is this correct?

[alick]

There is a difference between the RDML and RDMLX BIFs.

The RDML BIF cannot access the function internals to determine the working list field definition, so the SERVICE_LIST keyword is required on the command.

The RDMLX BIF can access the working list field definition, so the SERVICE_LIST keyword is not required and ignored.

RDML

1. The following command will only send the command string to the service.

use builtin(JSM_COMMAND) with_args('TEST KEY(VALUE)') to_get(#JSMSTS #JSMMSG)


2. The following command will send the command string and all fields in the function to the service.

use builtin(JSM_COMMAND) with_args('TEST KEY(VALUE) SERVICE_EXCHANGE(*FIELD)') to_get(#JSMSTS #JSMMSG)


3. The following command will send the command string, the working list and all fields in the function to the service.

use builtin(JSM_COMMAND) with_args('TEST KEY(VALUE)') to_get(#JSMSTS #JSMMSG #WRKLST)

Note: implied SERVICE_EXCHANGE(*FIELD)

If a working list and the associated SERVICE_LIST keyword is used, then all fields are passed and a SERVICE_EXCHANGE(*FIELD) is not required on the same command.


RDMLX

1. The following command will only send the command string to the service.

use builtin(JSMX_COMMAND) with_args(#JSMXHDLE 'TEST KEY(VALUE)') to_get(#JSMXSTS #JSMXMSG)


2. The following command will send the command string and all fields in the function to the service.

use builtin(JSMX_COMMAND) with_args(#JSMXHDLE 'TEST KEY(VALUE) SERVICE_EXCHANGE(*FIELD|*FIELDS)') to_get(#JSMXSTS #JSMXMSG)


3. The following command will send the command string and working list to the service.

Note: the function fields are not sent.

use builtin(JSMX_COMMAND) with_args(#JSMXHDLE 'TEST KEY(VALUE)') to_get(#JSMXSTS #JSMXMSG #WRKLST)


4. The following command will send the command string, all fields in the function and working list to the service.

use builtin(JSMX_COMMAND) with_args(#JSMXHDLE 'TEST KEY(VALUE) SERVICE_EXCHANGE(*FIELD|*FIELDS)') to_get(#JSMXSTS #JSMXMSG #WRKLST)


5. The following command will send the command string and the function fields defined in the field list to the service.

use builtin(JSMX_COMMAND) with_args(#JSMXHDLE 'TEST KEY(VALUE)' #FLDLST) to_get(#JSMXSTS #JSMXMSG)


6. The following command will send the command string and function fields defined in the field list and the working list to the service.

use builtin(JSMX_COMMAND) with_args(#JSMXHDLE 'TEST KEY(VALUE)' #FLDLST) to_get(#JSMXSTS #JSMXMSG #WRKLST)

[alick]

It is only after pressing the submit, do you notice a mistake or something missing

The SERVICE_LIST keyword is missing from some RDML example.

3. The following command will send the command string, the working list and all fields in the function to the service.

use builtin(JSM_COMMAND) with_args('TEST KEY(VALUE) SERVICE_LIST(...)') to_get(#JSMSTS #JSMMSG #WRKLST)

Note: implied SERVICE_EXCHANGE(*FIELD)

If a working list and the associated SERVICE_LIST keyword is used, then all fields are passed and a SERVICE_EXCHANGE(*FIELD) is not required on the same command.

[jyoung]

Thanks alick.

Those examples and descriptions help A LOT.

This should really be made part of the docs IMHO. Knowing / understanding that there is a difference between RDML and RDMLX BIFs and the different ways you interact with them can save some folks a good amount of headaches.

Thanks again!
Joe