9 92 GET_KEYWORD

You are here:

9.92 GET_KEYWORD_STRING

Note: Built-In Function Rules Usage Options

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: A - Alphanumeric N - Numeric 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