Functions

apiUi has a number of build-in function. This page contains a short description for each one.

AccordingSchema

boolean AccordingSchema (aItem)

Tests if an item has a value according schema. In case the item itself is a group, the group is tested against the schema

if AccordingSchema (rpy.GetRelation.AccountInformation) then
{
  …
}

AddRemark

void AddRemark (aString)

Adds a remark. In case this statement is in a operation script, the remark will be added to the log and be visible in the logs tab. If the statement is in a script, available from the main menu, then the remark is added to the notifications and therefor visible in the notifications tab.

AddRemark ('this is a remark');

AssignAnyType

void AssignAnyType (aDestGroup, aSrcGroup)

Assigns (copies) the source group to the destination group, irrespective of the schema of the destination group.

AssignAnyType (req.api.a, rpy.api.b);

Assigned

boolean Assigned (aItem)

Tests if the group or element exists (is assigned a value).

if Assigned (rpy.GetRelation.AccountInformation) then
{
  …
}

AsXmlString

string AsXmlString (aId)

Returns the (group)item as an XML string.

string ws.s := AsXmlString (rpy.GetRelation.AccountInformation);

ClearLogs

void ClearLogs ()

Clears the console logs.

ClearSnapshots

void ClearSnapshots ()

Clears the console snapshots. Snapshotfiles are not removed from the project log folder.

CreateJUnitReport

void CreateJUnitReport (aName)

To support CI/CD, creates a JUnit report in the project reportfolder.

CreateSnapshot

void CreateSnapshot (aName)

Creates a snaphot with the given name. New log-entries (meaning not yet written to an earlier snapshot) are written to the new snapshot, stored in the project folder (see Project->Options->General->projectFolders) with the provided filename.

CreateSnapshot ('mysnapshot');

CreateSummaryReport

void CreateSummaryReport (aName)

To support CI/CD, creates a test summary report (html) showing regression and coverage. The created report is stored in the projects report folder (see Project->Options->General->projectFolders)

CreateSummaryReport ('mytestsummary');

DateTimeToJulianStr

string DateTimeToJulianStr (aDateTime)

Returns a string with the provided datetime converted to a Julian datetime.

string ws.julianstring := DateTimeToJulianStr (Now ());

DateTimeToTandemJulianStr

string DateTimeToTandemJulianStr (aDateTime)

Returns a string with the provided datetime converted converted to a Julian datetime as used in Tandem (Guardian) machines.

string ws.tandemjulianstring := DateTimeToTandemJulianStr (Now ());

DateTimeToUnix

integer DateTimeToUnix (aDateTime)

Returns an integer with the provided datetime converted to Unix format.

integer ws.unixdatetime := DateTimeToUnix (aDateTime);

DateTimeToXml

string DateTimeToXml (aDateTime)

Returns a string with the provided datetime converted to a XML/JSON format.

string ws.xmlstring := DateTimeToXml (aDateTime);

dbLookUp

string dbLookUp (aTable, aValueColumn, aReferenceColumn, aReferenceValue)

Returns the value from the ValueColumn from the database table where the reference column has the referencevalue. Requires that you have connected a database. See Embedded SQL statements for more information. The reference value does not have to be unique in the reference column. DbLookUp will return the last value that was queried from the database. In case no match is found, this function will return an empty string.

Rpy.Customer.Gender := DBlookUp ( ‘ListOfValues’
                                , ‘PresentationValue’
                                , ‘CodeValue’
                                , Customer.Gender
                                );

DecEnvNumber

integer DecEnvNumber (aKey)

Decreases the environment variable indicated by aKey and returns the new value as a number.

integer ws.n := DecEnvNumber ('loopcounter');

ExecSql

void ExecSql (aQuery)

Executes an SQL query. Requires that you have connected a database. The function does an automatic commit after the SQL is executed.

ExecSql ('update relation set name = "Jan" where relationid = "12"');

ExecuteOperationScript

void ExecuteOperationScript (aOperation)

Executes the script of the named operation

if ws.n < 10 then
  ExecuteOperationScript ('QueryContacts');

ExecuteScript

void ExecuteScript (aScript)

Executes the script indicated by aScript.

if ws.n < 10 then
  ExecuteScript ('myscript');

ExecuteScriptLater

void ExecuteScriptLater (aScript, aLaterMs)

The named script is executed after aLaterMs milliseconds. The requesting script proceeds immediatly.

ExecuteScriptLater ('myPostponedScript', 12000);

Exit

void Exit ()

Terminates execution of the current script.

if ws.n > 99 then Exit ();

FetchDefaultDesignMessage

void FetchDefaultDesignMessage (aOperation)

Fills runtime data for the script with values from the default message. Applies to both request and response data.

FetchDefaultDesignMessage ('GetRelationPost');

FormatDate

string FormatDate (aDate, aMask)

Returns a date formatted as a string. You specify the format by a mask that tells how you would like to see February, 3, 1901.

ws.string := FormatDate (Today (), '02/03/1901');

GenerateGUID

string GenerateGUID ()

Returns a new generated GUID.

string ws.uuid := GenerateGUID ();
AddRemark (ws.uuid); // will show something like 566A5BF8-0E94-47EE-A6BF-45F212C858E9

GetContext

string GetContext ()

Returns the name of the current apiUi context.

string ws.savecontext := GetContext ();

GetEnvNumber

integer GetEnvNumber (aKey)

Returns an apiUi environment variable as a number. Combined with other SetEnv functions, this enables you to pass information between service invocations. In case the environment variable does not exist, zero is returned.

if GetEnvNumber ('nn') = 100 then
  Exit();

GetEnvNumberDef

integer GetEnvNumberDef (aKey, aDefault)

if GetEnvNumberDef ('nn', 101) = 100 then
  Exit();

GetEnvVar

string GetEnvVar (aKey)

if GetEnvVar ('Should I exit') = 'true' then
  Exit();

GetEnvVarDef

string GetEnvVarDef (aKey, aDefault)

if GetEnvVarDef ('Should I exit', 'not yet') = 'true' then
  Exit();

GetEnvVarDefT

string GetEnvVarDefT (aKey, aDefault, aSeparator, aIndex)

Returns an apiUi environment variable as a string. Combined with other SetEnv functions, this enables you to pass information between service invocations. In case the environment variable not exists, the value of aDefault is returned. Otherwise, the returned value is the n-th item of separated list of values. If the index exceeds the number of available strings, then the last one is returned. Values have to be separated by a string that equals aSeparator.

string ws.s;
SetEnvVar ('avar', 'one;two');
{
  ws.s := GetEnvVarDefT ('avar', 'zero', ';', 1);
  AddRemark (ws.s); // will show 'one'

  ws.s := GetEnvVarDefT ('avar', 'zero', ';', 2);
  AddRemark (ws.s); // will show 'two'

  ws.s := GetEnvVarDefT ('avar', 'zero', ';', 3);
  AddRemark (ws.s); // will also show 'two'

  ws.s := GetEnvVarDefT ('avar', 'zero', ';', 4);
  AddRemark (ws.s);
}

Executing the above example will result in

one
two
two
two

HostName

string HostName ()

Returns the IP-hostname.

ifthen

string ifthen (aCondition, aTrueString, aFalseString)

Returns aTrueString in case aCondition is true. Else returns aFalseString.

string ws.s := ifthen (2 = 3, '2 = 3', '2 <> 3');
AddRemark (ws.s); // will show '2 <> 3'

IncEnvNumber

integer IncEnvNumber (aKey)

Returns an apiUi environment variable as a number. Enables you to count over service invocations. If, at first call, the environment variable not exists, 1 (one) is returned

integer ws.n;
ws.n := IncEnvNumber ('avar');
AddRemark (NumberToStr (ws.n)); // will show '1'
ws.n := IncEnvNumber ('avar');
AddRemark (NumberToStr (ws.n)); // will show '2'
ws.n := IncEnvNumber ('avar');
AddRemark (NumberToStr (ws.n)); // will show '3'

Latin1Str

string Latin1Str (aString)

Returns aString converted to Latin1

AddRemark (Latin1Str ('Ĥĩĩ')); // will show 'Hii'

LengthStr

integer LengthStr (aString)

Returns the length of aString

LogsFromRemoteServer

void LogsFromRemoteServer ()

Fetches the logs from the remote server.

LowercaseStr

string LowercaseStr (aString)

Retruns aString in lower case.

MatchingEnvVar

for each MatchingEnvVar (aRegExpr) as string

A For-Each-As statement. Returns a list with the environment variables that match the regular expression.

string ws.key;
SetEnvVar ('A1', 'one');
SetEnvVar ('A2', 'two');
SetEnvVar ('A3', 'three');
SetEnvVar ('B4', 'four');

for each MatchingEnvVar ('A.*') as ws.key do
{
  AddRemark (ws.key); // will show 'A1', 'A2' and 'A3'
}

for each MatchingEnvVar ('A.*') as ws.key do
{
  AddRemark (GetEnvVar (ws.key)); // will show 'one', 'two' and 'three'
}

MD5

string MD5 (aString)

Returns the MD5 hash-total for the argument-string.

MessageName

string MessageName ()

Retuns the name of the message-candidate beeing processed.

MessageOfOperation

for each MessageOfOperation (aOperation) as string

A For-Each-As statement. Returns a list with the names of message-candidates for the named operation.
Within the attached code-block, the working storage of the operation is filled with data from the corresponding message.

string ws.s;
for each MessageOfOperation ('GetRelation1') as ws.s do
{
  AddRemark (ws.s);
  RequestOperation ('GetRelation1');
}

MessagingProtocol

string MessagingProtocol ()

Returns the messaging protocol for the current operation (only applicable for outbound operations)

NameCaseStr

string NameCaseStr (aString)

Returns aString with first character of each word in uppercase, all others lowercase.

AddRemark (NameCaseStr ('jAn BOUWMAN')); // will show 'Jan Bouwman'

NewDesignMessage

void NewDesignMessage (aOperation, aName)

Adds a new message candidate to the denoted operation. The new candidate's name is aName.

NewLine

string NewLine ()

Returns a string which is a NewLine. Depends on operating system.

AddRemark ('Jan' + NewLine () + 'Bouwman'); // will show Jan and Bouwman separated by a new line

NowAsStr

string NowAsStr ()

Returns current date-time as string (conforming XML/JSON standard)

NumberToStr

string NumberToStr (aNumber)

Converts a number to a string

Occurrences

integer Occurrences (aElement)

Returns the number of repeating elements

integer ws.n := Occurrences (rpy.relation.servicerequests);

OperationCount

integer OperationCount ()

Returns the number of times the current operation is called since startup or since last call to ResetOperationCounters.

OperationName

string OperationName ()

Returns the name of the current operation.

PopulateFromXmlString

void PopulateFromXmlString (aId, aString)

Fills the named structure with values from aString. aString should be filled with a valid XML string with correponding element names.

PromptReply

void PromptReply ()

Shows the reply message in a pop-up screen. Enables you to view and alter a reply on runtime. This function should be used with care because execution is halted until someone closes the screen.

if req.GetCustomerDetails.CustomerId = 'JanBo' then
{
  PromptReply();
  Exit();
}

PromptRequest

void PromptRequest ()

Shows the request message in a pop-up screen. Enables you to view and alter a request on runtime. This function should be used with care because execution is halted until someone closes the screen.

if req.GetCustomerDetails.CustomerId = 'JanBo' then
  PromptRequest();

PushOperationToRemoteServer

void PushOperationToRemoteServer (aOperation)

Pushes the named operation to the remote server.
Make sure you have a remote server connected.
Disabled when you are running apiUiServer as remote server.

PushProjectToRemoteServer

void PushProjectToRemoteServer ()

Pushes current project to the remote server. Make sure you have a remote server connected.

RaiseError

void RaiseError (aString)

Raises an exception and exits current script. The requestor will receive an HTTP 500 Internal error with the argument as message.

if req.GetCustomerDetails.CustomerId = 'RaiseError' then
  RaiseError('This is an error raised intentionally from apiUi script');

RaiseHttpFault

void RaiseHttpFault (aResponseCode, aResponseText, aResponseContentType)

Exits current script. The requestor will receive the specified HTTP responsecode with the second argument as body and thirth as ContentType.

if req.GetCustomerDetails.CustomerId = 'x401' then
  RaiseHttpFault('401', 'This is an error raised intentionally from apiUi script', 'text/plain');

RaiseSoapFault

void RaiseSoapFault (aFaultCode, aFaultString, aFaultActor, aDetail)

Raises a soapfault and exits current script.

if req.GetCustomerDetails.CustomerId = 'RaiseSoapFault' then
  RaiseSoapFault ('cd', 'str', 'actr', 'dtl');

The requester will receive an HTTP 500 error (‘Internal server error’) with a soapfault as message.

<SOAP-ENV:Fault>
  <faultcode>cd</faultcode>
  <faultstring>str</faultstring>
  <faultactor>actr</faultactor>
  <detail>dtl</detail>
</SOAP-ENV:Fault>Tekstuele omschrijving

RaiseWsdlFault

void RaiseWsdlFault (aFaultCode, aFaultString, aFaultActor)

Raises a soapfault and exits current script. The soapfault content depends on the soapfault message being used. The designer determines which soapfault will be returned by assigning values to desired message.

if req.GetCustomerDetails.CustomerId = 'RaiseSoapFault' then
{
  {assign soap fault values here}
  RaiseWsdlFault ('cd', 'str', 'actr');
}

The requester will receive an HTTP 500 error (‘Internal server error’) with a soapfault as message.

<SOAP-ENV:Fault>
  <faultcode>cd</faultcode>
  <faultstring>str</faultstring>
  <faultactor>actr</faultactor>
  <detail>
    …
  </detail>
</SOAP-ENV:Fault>

Random

number Random (aLow, aHigh)

Generates a random number between aLow and aHigh.

RegExprMatch

for each RegExprMatch (aString, aRegExpr) as string

A For-Each-As statement. Returns a list of substrings within aString matching the regular expression.

string ws.match;
for each RegExprMatch ('1234abcd333efg', '\d{2}') as ws.match do
{
  AddRemark (ws.match); // will show '12', '34' and '33'
}

RegExprSafeStr

string RegExprSafeStr (aString)

Returns aString with all characters that are meta characters in regular expressions escaped by preceeding it with a backslash.

  AddRemark (RegExprSafeStr ('a[b]c')); // will show 'a\[b\]c'

RemoveDesignMessages

void RemoveDesignMessages (aOperation)

Removes all of the message candidates, except the default one, for the denoted operation.

ReplyAsText

void ReplyAsText (aOperation)

Returns a string containing a reply as tekst, based on values from the message-candidate. Contains XML, JSON or COBOL, depending on the operation.

RequestAsText

string RequestAsText (aOperation)

Returns a string containing a request as tekst, based on values from the message-candidate. Contains XML, JSON or COBOL, depending on the operation.

RequestOperation

string RequestOperation (aOperation)

Sends a request for an operation and waits for response.

if StrToNumber(req.Transaction.Amount) > 10000 then
{
  RequestOperation ('checkRemarkableTransactionReq');
}

RequestOperationLater

void RequestOperationLater (aOperation, aLaterMs)

Asynchronously sends a request after aLaterMs waiting time. The calling script does not wait but procedes immediately.

RequestOperationLater ('GetVerifiedAddress1', 12000);

ResetEnvVar

void ResetEnvVar (aKey)

Removes an apiUi environment variable.

ResetEnvVars

void ResetEnvVars (aRegularExpr)

Removes all apiUi environment variables that match the regular expression.

If rpy.Customer.CustName = ‘init’ then
 ResetEnvVars (‘Cust.*’);

ResetOperationCounters

void ResetOperationCounters ()

Resets all operation counters.
See also OperationCount

ResetStateMachine

void ResetStateMachine ()

Resets the state machine.
For each scenario, the state is set to 'Started'.

ResolveAliasses

string ResolveAliasses (aString)

Returns the argument with all aliasses resolved in the current context. See also context switching

ReturnString

void ReturnString (aString)

When applied in the script for an inbound service-call, this statement will overrule all normal apiUi processing and will cause apiUi to respond to the service-call with the given string.

Rounded

number Rounded (aNumber, aDecimals)

Rounds a number to a number of decimals. Negative value for aDecimals is allowed.

AddRemark (NumberToStr (Rounded (12345.678 , -2))); // will show '12300'
AddRemark (NumberToStr (Rounded (12345.678 ,  2))); // will show '12345.68'

SaveLogs

void SaveLogs (aFileName)

Saves the logs to the named file.

SendOperationRequest

void SendOperationRequest (aOperation, aCorrelation)

Depricated

SendOperationRequestLater

void SendOperationRequestLater (aOperation, aCorrelation, aLater)

Depricated

SeparatedString

for each SeparatedString (aString, aSeparator) as string

A For-Each-As statement. Returns a list with the individual strings from a string containing a value list.

string ws.s;
for each SeparatedString ('Jan;Piet;Klaas;Kees', ';') as ws.s do
{
  AddRemark (ws.s); // will show the strings 'Jan', 'Piet', 'Klaas' and 'Kees'
}

SeparatedStringN

string SeparatedStringN (aString, aSeparator, aIndex)

Returns the n-th substring from a string containing separated substrings.

AddRemark (SeparatedStringN ('Jan;Kees;Klaas;Piet', ';', 3)); // will show 'Klaas'

SeparatedStringT

string SeparatedStringT (aString, aSeparator, aIndex)

Returns the n-th substring from a string containing separated substrings. In case n exceeds the number of substrings, the last substring is returned.

AddRemark (SeparatedStringT ('Jan;Kees;Klaas;Piet', ';', 3)); // will show 'Klaas'
AddRemark (SeparatedStringT ('Jan;Kees;Klaas;Piet', ';', 4)); // will show 'Piet'
AddRemark (SeparatedStringT ('Jan;Kees;Klaas;Piet', ';', 5)); // will show 'Piet'

SetContext

string SetContext (aContextName)

Sets a new context as used by ResolveAliasses, returning the old one.
See also context switching

string ws.oldcontext := SetContext ('myNewContext');
...
SetContext (ws.oldcontext); // restores...

SetEnvNumber

integer SetEnvNumber (aKey, aNumber)

Sets the value of environment variable aKey to aNumber, returns the existing value

SetEnvNumber ('myVar1', 1);

SetEnvVar

string SetEnvVar (aKey, aValue)

Sets the value of environment variable aKey to aValue; Returns the existing value

if GetEnvVar ('Should I exit') = 'true' then
{
  SetEnvVar ('Should I exit', 'false');
  Exit();
}

SHA1

string SHA1 (aString)

Returns the SHA1 hash-total for the argument-string.

ShowMessage

void ShowMessage (aString)

Adds a notification with the given string.
See also AddRemark

SiebelNowAsStr

string SiebelNowAsStr ()

Returns a string containing the systime in Siebel (trademark) format

AddRemark (SiebelNowAsStr ());// will show systime in format MM/DD/YYYY HH:mm:SS

SiebelTodayAsStr

string SiebelTodayAsStr ()

Returns a string containing the sysdate in Siebel (trademark) format

AddRemark (SiebelTodayAsStr ());// will show systime in format MM/DD/YYYY

Sleep

void Sleep (aMilliSeconds)

Suspends execution of the script for a specified number of milliseconds.

SqlQuotedStr

string SqlQuotedStr (aString)

yet to be delivered

yet to be delivered

SqlSelectResultRow

for each SqlSelectResultRow (aSqlSelectQuery) as string

A for-each-as statement. Returns a list with the rows as tab-separated strings for each result row of the sql query.

string ws.row;
for each SqlSelectResultRow ('select * from relation') as ws.row do
{
  AddRemark (SeparatedStringN (ws.row, Tab (), 1) + ' : ' + SeparatedStringN (ws.row, Tab (), 2));
}

The above sample will show the content of first and second column for each row of table with name 'relation'

StrFromClipboard

string StrFromClipboard ()

Returns the content of the clipboard as string.

StrHasRegExpr

string StrHasRegExpr (aString, aRegExpr)

If aString has a substring that matches the regular expression, then it will return that substring, otherwise it will return an empty string.

AddRemark (StrHasRegExpr ('this string does not contain 2 numbers', '\d+')); // will show '2'

StrMatchesRegExpr

string StrMatchesRegExpr (aString, aRegExpr)

Returns an empty string if the delivered string does not match the regular expression.

if StrMatchesRegExpr ('1234567890', '\d+') then
  AddRemark ('will show'); // will show
if StrMatchesRegExpr ('1234567AAA', '\d+') then
  AddRemark ('will not show'); // will not show

StrOfChar

string StrOfChar (aChar, aNumber)

Returns a string containing aChar repeated aNumber times.

string ws.s := '123';
AddRemark (StrOfChar ('0', 15 - LengthStr (ws.s)) + ws.s);  // will show '000000000000123'

StrToDate

datetime StrToDate (aString)

Will convert aString from standard XML/JSON format to the apiUi internal format. Sometimes needed for date calculation.

StrToDateTime

datetime StrToDateTime (aString)

Will convert aString from standard XML/JSON format to the apiUi internal format. Sometimes needed for date calculation.

StrToFile

void StrToFile (aFileName, aString)

Will write the string to a disk file.

StrToNumber

number StrToNumber (aString)

Converts a string to a number.

SubStr

string SubStr (aString, aStart, aLength)

Returns aLength characters of the substring starting from aStart. In case the end of the source string is reached before the aLength characters are copied, less characters are returned.

SwiftNumberToStr

string SwiftNumberToStr (aNumber)

Tekstuele omschrijving

yet to be delivered

SwiftStrToNumber

number SwiftStrToNumber (aString)

Tekstuele omschrijving

yet to be delivered

Tab

string Tab ()

Returns a string containing a single tab-character (decimal 9).

TodayAsStr

string TodayAsStr ()

Returns system date in XML/JSON format (YYYY-MM-DD)

UnixToDateTime

datetime UnixToDateTime (aUnixDateTime)

Returns a datetime with the provided datetime converted to apiUi internal format.

timestamp ws.datetime := UnixToDateTime (aUnixDateTime);

UppercaseStr

string UppercaseStr (aString)

Returns aString converted to uppercase.

UserName

string UserName ()

Returns the Operating-System login-name of the user

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search