9.96 FORMAT_STRING
Þ Note: Built-In Function Rules.
This Built-in Function returns a character string which is built from an input Format Pattern. The Format Pattern can consist of text plus field values. Editing options may be applied to the field values.
Special Note: All characters preceded by a colon (:) will be treated as a field name and ends with either one of the following characters () space and colon.
For use with
|
Arguments
|
Return Values
|
Technical Notes
- Field names are preceded by a colon (:).
Example Format Pattern =
Employee :givename :surname with number :EMPNO was not found.
Return Formatted String =
Employee DARREN BROWN with number A0001 was not found.
when field givename contains the value "DARREN", field surname contains the value "BROWN" and field empno contains the value "A0001"
- Fields used in the Format Pattern must be used elsewhere in the RDML function.
Fields may be defined in the repository or internally within the function.
- To include a colon (:) in the returned Formatted String, use two colons in the input Format pattern.
Example Format Pattern=
Employee no:::empno
Returned Formatted String=
Employee no:A0001
- To include a character straight after the field, use brackets().
Example Format Pattern=
Employee no:::empno()NoSpace
Returned Formatted String=
Employee no:A0001NoSpace
- Formatting option/s may be applied to a field value and specified in the Format Pattern.
Multiple options may be applied to a field value.
Formatting options must immediately follow the field name and be contained within brackets ().
Example Format Pattern=
Employee :givename(substr,1,1 UPPER). :SURNAME(trim upper)
Returned Formatted String=
Employee D. BROWN
- When multiple formatting options are specified for a field value, the options are applied in the following order
1. edit code
2. substring
3. trim trailing (trim)
4. trim leading (triml)
5. trim all
6. lower
7. upper
- The Edit code formatting option are applied only to numeric fields.
If an edit code formatting option is specified for a character field, it will be ignored.
- Edit codes which suppress leading zeroes will remove any resulting leading blanks.
DBCS considerations
Text sections of the Format Pattern may contain DBCS or mixed characters. However the :field specification must be entered in single byte mode. Also any text section must be a complete string with the correct pairing of shift out/ shift in characters.
The substring format option is not DBCS sensitive by default. To enable DBCS, set the second optional argument to 'YES'. Note that the number for the start position and length are in character count, not in byte and the shift in and shift out bytes are not counted.
Example
This example retrieves information from a file and formats different lines into a standard browse list. A variety of formatting options are used to format field values.
FUNCTION OPTIONS(*DIRECT)
DEFINE FIELD(#STRING) TYPE(*CHAR) LENGTH(75) COLHDG('Details') INPUT_ATR(LC)
DEFINE FIELD(#PATERN) TYPE(*CHAR) LENGTH(256) INPUT_ATR(LC)
DEF_LIST NAME(#BRWLST) FIELDS((#STRING))
**********
SELECT FIELDS((#EMPNO) (#GIVENAME) (#SURNAME) (#STARTDTE) (#TERMDATE) (#ADDRESS1) (#ADDRESS2) (#ADDRESS3) (#SALARY) (#POSTCODE)) FROM_FILE(PSLMST)
CHANGE FIELD(#PATERN) TO('''EMPLOYEE:: :empno :GIVENAME(substr,1,1 upper).:surname(upper trim)''')
EXECUTE SUBROUTINE(ADDTOBRW)
CHANGE FIELD(#PATERN) TO(''' Start :startdte(editcode ,Y) Salary $:salary(editcode,J)''')
EXECUTE SUBROUTINE(ADDTOBRW)
CHANGE FIELD(#PATERN) TO(''' Address:: :ADDRESS1(trim) :ADDRESS2(TRIM)''')
EXECUTE SUBROUTINE(ADDTOBRW)
CHANGE FIELD(#PATERN) TO(''' :aDDRESS3(trima ll) :postcode(editcode,4)''')
EXECUTE SUBROUTINE(ADDTOBRW)
ENDSELECT
**********
DISPLAY BROWSELIST(#BRWLST)
RETURN
********** -------------------------------------------
SUBROUTINE NAME(ADDTOBRW)
USE BUILTIN(FORMAT_STRING) WITH_ARGS(#PATERN) TO_GET(#STRING)
ADD_ENTRY #BRWLST
ENDROUTINE .