Transaction service call

Required input values

This table shows the required input values for a transaction service call:

Field Description
_PDL

The product line name. This value is the data area, and the corresponding product line is looked up. Required field. If this parameter is missing, the ProductLine attribute from the RM system for the user making the query is used.

The value of the user’s ProductLine attribute in the RM system.

_TKN

The token name. Required.

If only the program code is sent, the token is defaulted to the .0 screen. If that is not found, the .1 screen is used. For example, if _TKN=CU01 is sent, the CU01.1 token is loaded.
Token Fields

The token fields used for the transaction.

The fields can be sent using the field number (_f#) or the long field name. The field number is the sequential number of the field found in the tranmap.

Optional input values

This table shows the optional input values for a transaction service call:

Field Description
_DATEFMT _DATEFMT=ALL indicates that formatted dates are to be passed and returned. If this tag is NOT sent, it means that the dates returned should be unformatted and in the format of ccyymmdd.
_DTLROWS

Empty detail rows.

TRUE All detail rows are returned, even if they do not contain data.

FALSE Detail rows that have no data in them can not be returned. This tag is primarily used by consumers who need to process each detail line and do not want to bother processing through empty detail lines.

The default is TRUE.
_EVT

Event Type.

If specified, the transaction process knows that a partial transaction may be present and to act accordingly to fill in empty data if necessary.

ADD For this event type, no pre-Inquire is performed.

CHG This event type forces a pre-inquire on the data entered. In other words, not all the data related to the token need be passed in advance, only the necessary fields for the transaction. An inquire is done first with this event type and the blank fields are filled in behind the scenes. Then the function code passed in is executed.

If the _EVT tag is not sent, the transaction service can determine whether the pre-inquire should be performed based on function code.

Allowing the transaction service to decide whether to pre-inquire is recommended; sending _EVT=ADD in the incorrect situation could corrupt data
_IGNREQD

Ignore Required Fields.

0 Validates required fields and value lists.

1 Does not validate the field values.

The default is 0.
_INITDTL Initializes the detail fields after a pre-emptive inquire caused by the _EVT=CHG parameter.
_LFN

Long Field Names.

If specified, the long name for the field is returned instead of than the field number.

In the case of the FldNbr tag that is returned, if _LFN value is:

ALL All fields, including FldNbr, are returned with the long name for the field.

TRUE All fields are returned with the long name for the field, except FldNbr, which is returned with the field number (_f#).
_RTN

Return Type.

This parameter specifies which data to return in the response.

DATA Returns the full transaction information. All of these are returned: field tags, messaging and error tags, and formatting tags that were passed in.

MSG Only return the Messaging information (message, message number, field number – populated only on an error).

SENT Returns the tags that were sent. It also returns second instances of the _PDL and _TKN tags – presumably to ensure that these have not changed during processing. The returned tags are not necessarily in the same order as they were passed in on the request.

The default is DATA.
_CACHE

Transaction Service can cache the results of the last transaction on the server.

TRUE The caching can be turned on by setting the _CACHE=TRUE. If this tag is not provided to the transaction service, it can not cache by default. If this tag is set to TRUE, then the _TRANSID generated and returned by the transaction service needs to be sent back during the subsequent transactions.

FALSE The transaction data is not cached on the server side. This is equivalent to not sending in the tag at all.

_CACHE and _TRANSID are intended to improve performance for form-based online transaction processing. You can use a valid _TRANSID to bypass the pre-inquire step for an update transaction.

A _TRANSID value has a limited lifetime, after which the transaction is dropped from the cache. (The length of the lifetime of a cached transaction is controlled by the file $LAWDIR/system/appservercache.xml. In this file, the timeToIdleSeconds and timeToLiveSeconds values in the tranIdCache node determine how long a transaction id is valid.)

If you submit an update transaction with an expired _TRANSID, the update can fail, an error can be returned, and a _STALEDATA=TRUE flag can be returned by the transaction service. (_STALEDATA flag can generate if staleData is enabled in %LAWDIR%\system\iosconfig.xml. Additionally, if _STALEDATA is returned by a transaction service, it needs to be sent back during subsequent transactions).

In considering whether to use the _CACHE and _TRANSID tags in your application, you should consider whether significant time can elapse between inquiry and update events.

Return values

This table shows the return values for a transaction service call:

Field Description
Message The localized message.
MsgNbr

The message number.

000 Indicates no error.

*** Indicates an error occurred in Transaction code.

Three-digit code An application error number defined in msgmnt.
FldNbr The field number or name (if _LFN=ALL is specified). If an error has occurred, this can be the related field if applicable.
_VAL Returns FALSE if the _IGNREQD request parameter was set to ‘1’.
_PRE Pre-emptive inquire. This tag is returned if a pre-emptive inquire has taken place.

Unsupported input values

Release 9.0.x supported these values for calls to AGS which are no longer in 9.0.x calls to Transaction. This table shows the unsupported input values for a transaction service call:

Field Description
_OUT Specifies output type. Only the XML output type is supported for 9.0.x.
_ONLOAD JavaScript output parameter.
_UNM User name.
_PFC Pre-emptive function code.
_PRE This is a return tag only and has no meaning if it is passed in (see above).
_UFD User Fields.
_VFMT Variable decimal format.
_MSGTARGET JavaScript output only.
_LONG Text output only.
_IGNREQ Replaced with _IGNREQD.
_DELIM MS output delimiter.
_DTLSEP For the XML output, ‘r’ is always the detail separator.
_XSL XSL transformations are handled by the TransformFilter in 9.0.x.
_LNG Language. This parameter can be used to override the user’s language defined in RM. The default language can be specified by using a blank value.

Detail line processing

Previously, AGS had the option to index the detail lines starting from row 1 (_f1r1). In the Transaction Service the detail line is now indexed from row 0 (_f1r0). Those using the new Transaction Service need to make corresponding changes to their code.

Error formatting

The Transaction Service returns error messages in an XML format, regardless of the value of the OUT parameter. To view an example of this format, make a call without any parameters.

Sample calls

Because of IOS architectural changes, calls to the Transaction, Data and Drill services are made through a common servlet (Router) in 9.0.x. Calls to Transaction can be made using the GET method with a query string or using the POST method with an XML document. We recommend using a query builder tool to generate the transaction query strings.

These are some sample calls:

http://machine:port/servlet/Router/Transaction/Erp?_PDL=APPS810&_TKN=
CU01.1&_DATEFMT=ALL&_f0=CU01.1&_f1=I&_f2=USD&_f3=&_f4=&_f5=&_f6=&_f7=&_
f8=Multiple%20Entry

http://machine:port/servlet/Router/Transaction/Erp?_PDL=APPS810&_TKN=
CU01.1&_DATEFMT=ALL&_f0=CU01.1&_f1=I&_f2=USD&_f3=&_F4=&_f5=&_f6=&_f7=
&_f8=Multiple%20Entry&_RTN=MSG

http://machine:port/servlet/Router/Transaction/Erp?_PDL=APPS810&_TKN=
CU01.1&_DATEFMT=ALL&_f0=CU01.1&_f1=I&_f2=USD&_f3=&_f4=&_f5=&_f6=&_f7=&_
f8=Multiple%20Entry&_RTN=SENT

http://machine:port/servlet/Router/Transaction/Erp?_PDL=APP803&_TKN=
HR11.1&_DATEFMT=ALL*_fo=HR11.1&_f1=I&_f318=4321&_f320=1000&_OUT=XML

Form transfer response variables

This table shows the form transfer response variables for a transaction service call:

Parameter Description
Request

The transfer request type.

SENDMAPANDDATA

MANUALCFKEY

EXECCALLER

EXITWINDOW

RETURNKNS

RTNKNS_MANCF

MANSTACK

SENDMAPONLY

SENDMESSAGE

SENDERRANDDATA

SENDERRONLY

DISPLAYMAP

RETSTACK

RETSTACKKNS

The default value is SENDMAPANDDATA.
Screen The destination token.
FORMTYPE

The form type of the destination screen.

Window

Form
PassXlt The translated function code to pass to the screen that is executed when the screen is brought up in the Portal.
DspXlt The default translated function code to display on the screen after the transfer.

Touch files

This table shows the touch files for a transaction service call:

File Action
NOPRIOR If this file exists and the function is Previous, the transaction is not allowed.
DBUPPER If this file exists, all data is converted to uppercase before performing the transaction.
NOPARAMVAL Not supported.
USELATM No longer required. LATM is always used in 9.0.x.

Batch report parameters

This table shows the batch report parameters for a transaction service call:

Name Description
_STEPNBR If it is a multi-step job, indicates the step number of the job.

Security

For 9.0.x, for any field that is secured, a secured = “1” attribute is added to the field’s xml tag and no value is returned.

For example, if field _f2 is secured from the user’s view, the return xml tags for a token would look like this:

<_f1> some data </_f1>

<_f2 secured="1"></_f2>

  • <_f3> some data </_f3>
  • <_f4></_f4>
  • <_f5></_f5>
  • <_f6> some data </_f6>
  • <_f7></_f7>

Troubleshooting

There are many reasons that a transaction can have errors. Errors can be caused by lacobrts failures, database failures, failures in the latm processing, security code failures, etc.

Log files to look for errors:

  • $LAWDIR/system/ (security logs)
  • $LAWDIR/system/latm.log
  • $LAWDIR/system/ladb.log – database errors
  • $LAWDIR/system/joblog//lapm.pid – lacobrts errors

Change Actions

Because Security does not return values in secured fields, if a Change Action (Function code of Change), or an _EVT=CHG has been passed in, a pre-inquire on the data always takes place. This initial transaction is used to fill in possible secured fields.