9.92 GET_KEYWORD_STRING
Gets the keywords and their values from a string containing one ESF (external source format) statement.
Arguments
No | Type | Req/ Opt | Description | Min Len | Max Len | Min Dec | Max Dec |
|---|---|---|---|---|---|---|---|
1 | L | Req | Working list containing 'lines' of string from which keywords and their values will be retrieved. There is a limit of 1000 characters in total for this list. | 1 | 256 | ||
2 | N | Req | The length of working list entry for the 'lines' of the string from which keywords and their values will be retrieved. | 1 | 3 | 0 | 0 |
3 | A | Req | Tag name (command name) of the ESF statement that is being processed. | 1 | 10 | ||
4 | L | Req | Working list of keywords to search for. The calling RDML function must provide a working list with an aggregate entry length of exactly 16 bytes. Each list entry is formatted as follows: From - To Description 1 - 15 Keyword 16 - 16 Number of Values: S - Single Value L - List of Values | 16 | 16 |
Return Values
No | Type | Req/ Opt | Description | Min Len | Max Len | Min Dec | Max Dec |
|---|---|---|---|---|---|---|---|
1 | L | Req | Working List for keywords found. The calling RDML function must provide a working list with an aggregate entry length of exactly 25 bytes. Each list entry is formatted as follows: From - To Description 1 - 15 Keyword 16 - 20 First value list entry number for keyword 5,0 Signed 21 - 25 Last value list entry number for keyword 5,0 Signed | 25 | 25 | ||
2 | L | Req | Working List for values found The calling RDML function must provide a working list with an aggregate entry length of exactly 131 bytes. Each list entry is formatted as follows: From - To Description 1 - 1 Value Type: 2 - 101 Alpha value. Note: The alpha value is always enclosed in quotes. 102 - 131 Numeric value. Note: The numeric literal is a 30, 9 signed value. | 131 | 131 | ||
3 | L | Req | Working list for the leftover part of the searched string after the search keywords and their values have been removed. Each list entry is formatted as follows: From - To Description 1 - 2 Error code . Error codes are listed below. 3 - 22 The first 20 character string that was not recognized. | 1 | 22 |
Error codes
01 | Tag open delimiter was not a colon |
02 | Tag name does not start with an alpha character |
03 | Tag name to long - must be less/equal to 10 characters |
04 | Keyword does not start with an alpha character |
05 | Keyword Invalid - not found in declared keyword list |
06 | Keyword incomplete - end of string found |
07 | Keyword specified too long - must be less/equal to 15 characters |
08 | No Values specified for keyword |
09 | Value specified is too long |
10 | Multiple values specified for a single value list |
11 | Quoted value does not end in a quote |
12 | Invalid numeric literal value |
13 | More than one decimal format character specified for value |
14 | Digit portion of numeric literal value is longer than 21 |
15 | Decimal portion of numeric literal is longer than 9 |
16 | Command string longer than allowed maximum of 1000 characters |
17 | Tag close delimiter not specified |
18 | Value incomplete - end of string found |
19 | Expected tag name not found |
20 | Quoted value must be followed by a blank |
21 | End of keyword relator not specified |
22 | Keyword specified more than once |
Technical Notes
The returned keywords list will have an entry for each keyword searched for, in the order specified in the keywords to search for list. A keyword not found will have 0 as its first value list entry number.
Ensure all keywords specified in the working list of keywords to be searched for and the keywords specified within the ESF statement are in UPPERCASE.
The alpha value in the returned values list will always be there whether the value is alpha or numeric. The numeric value will only be nonzero if the value is numeric.
Alphanumeric values that contain lowercase characters and that are not enclosed in quotes will be converted to UPPERCASE.
Alphanumeric values must not contain embedded quotes.
The maximum length allowable for an alphanumeric value is 98, all alphanumeric values will be returned in quotes.
The string in the returned leftover list will consist of the search string where an error has occurred.
Example
A list has been constructed containing an ESF style statement. It has been determined that it is the RECORD statement. The value for FILENAME which is a single value keyword is required.
DEFINE FIELD(#KWD) TYPE(*CHAR) LENGTH(10)
DEFINE FIELD(#KWDTYPE) TYPE(*CHAR) LENGTH(1)
DEFINE FIELD(#LINE) TYPE(*CHAR) LENGTH(70)
DEFINE FIELD(#KWDSTR) TYPE(*DEC) LENGTH(3) DECIMALS(0)
DEFINE FIELD(#KWDEND) TYPE(*DEC) LENGTH(5) DECIMALS(0)
DEFINE FIELD(#VALTYPE) TYPE(*CHAR) LENGTH(1)
DEFINE FIELD(#VALALPHA) TYPE(*CHAR) LENGTH(50)
DEFINE FIELD(#VALNUM) TYPE(*DEC) LENGTH(30) DECIMALS(0)
DEFINE FIELD(#FILENAME) TYPE(*CHAR) LENGTH(10)
DEFINE FIELD(#LEFTCOUNT) TYPE(*DEC) LENGTH(5) DECIMALS(0)
DEF_LIST NAME(#KWDSRCH) FIELDS((#KWD) (#KWDTYPE))
TYPE(*WORKING)
DEF_LIST NAME(#STRSRCH) FIELDS((#LINE)) TYPE(*WORKING)
DEF_LIST NAME(#KWDFND) FIELDS((#KWD) (#KWDSTR) (#KWDEND)
TYPE(*WORKING)
DEF_LIST NAME(#VALFND) FIELDS((#VALTYPE) (#VALALPHA)
(#VALNUM)) TYPE(*WORKING)
DEF_LIST NAME(#STRLEFT) FIELDS((#LINE)) TYPE(*WORKING)
COUNTER(#LEFTCOUNT)
********** Construct list containing ESF:RECORD statement
. . . . . . . . . . . . . . . .
********** Clear the keyword search list
CLR_LIST NAMED(#KWDSRCH)
********** Put in search keywords
CHANGE FIELD(#KWD) TO(FILENAME)
CHANGE FIELD(#KWDTYPE) TO(S)
ADD_ENTRY TO_LIST(#KWDSRCH)
********** Get the keywords from the string
USE BUILTIN(GET_KEYWORD_STRING) WITH_ARGS(#STRSRCH #KWDSTR #KWD
#KWDSRCH) TO_GET(#KWDFND #VALFND #STRLEFT)
********** Handle error
IF COND('#LEFTCOUNT > 0')
********** error processing
. . . . . . . . . . . . . . . .
ELSE
********** Get the value for the file name keyword
GET_ENTRY NUMBER(1) FROM_LIST(#VALFND)
GET_ENTRY NUMBER(#KWDSTR) FROM_LIST(#VALFND)
CHANGE FIELD(#FILENAME) TO(#VALALPHA)
********** Use the file name
. . . . . . . . . . . . . . . .
ENDIF